blockforce-design-system 2.0.2 → 2.0.3

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/llms-full.txt ADDED
@@ -0,0 +1,2197 @@
1
+ # Blockforce Design System 2.0.2 (completo)
2
+
3
+ > Pacote `blockforce-design-system`. Storybook: https://designsystem.blockforce.ai
4
+
5
+ ## Regras de ouro
6
+
7
+ 1. **Procure a peça antes de criar uma nova.** Card, Tag, Toast, EmptyState, IconButton, Skeleton, Pagination, DatePicker, Matrix e as peças da árvore já existem. A lista completa está em `lib/ai/components.json`.
8
+ 2. **Nunca escreva cor, tamanho, raio ou sombra à mão.** Use o token do tema: `theme.colors.grey_2`, `theme.spacing.md`, `theme.radius.lg`, `theme.shadow.sm`. Em props de componente, use o nome (`color="primary"`, `padding="md"`).
9
+ 3. **Cores com os nomes de sempre:** `primary` (roxo), `secondary` (teal), `grey_1`…`grey_6`, `white`. Estados em `state.*`, fundos claros de estado em `stateSubtle.*`, texto de estado em `stateText.*`, gráficos em `chart.*`.
10
+ 4. **O gradiente é a marca e existe um só:** `theme.colors.brand.gradient`, a 45°, roxo → teal. Nunca outro ângulo nem outras cores.
11
+ 5. **Cor de estado é só para estado.** Verde é sucesso, laranja é alerta, vermelho é erro. O teal da marca não é cor de sucesso.
12
+ 6. **A fonte é Inter** (`theme.typography.fontFamily`). O projeto carrega a Inter de 300 a 700; o DS não carrega fonte.
13
+ 7. **Texto de frase em `grey_2`.** `grey_3` só em rótulo curto ou texto desabilitado.
14
+ 8. **Sem `style={{}}`.** Ajuste visual vai por prop do componente ou por `styled(...)` com tokens.
15
+ 9. **Celular é até 768px, inclusive** (`theme.breakpoints.md`), um corte só.
16
+ - **Como detectar:** no styled, use `media.down('md')`; no componente, `useIsMobile()`. Não invente outro corte (600, 720, 900).
17
+ - **Como testar:** toda tela funciona em 375px sem rolagem horizontal na página.
18
+ - **Como adaptar:** grade vira uma coluna. Tabela que as pessoas consultam no celular usa `mobileLayout="cards"`; as outras rolam dentro da própria tabela.
19
+ 10. **Nomes antigos funcionam, mas use os novos.** `CheckBox` → `Checkbox`, `DragNDrop` → `FileDropzone`, `Slider` → `Carousel`, `Treeview` → `TreeView`, `TablePagination` → `Pagination` com `totalItems`. O editor mostra os antigos riscados (`@deprecated`).
20
+
21
+ ## Como usar
22
+
23
+ ```tsx
24
+ import { ThemeProvider, defaultTheme, Card, Tag, Button } from 'blockforce-design-system'
25
+
26
+ export const App = () => (
27
+ <ThemeProvider theme={defaultTheme}>
28
+ <Card>
29
+ <Tag label="Aprovado" color="success" />
30
+ <Button>Salvar</Button>
31
+ </Card>
32
+ </ThemeProvider>
33
+ )
34
+ ```
35
+
36
+ Projetos que já usam o tema da plataforma continuam com `createTheme({...})`. Página pública com a marca do cliente usa `createClientTheme({ primary, accent, fontFamily })`.
37
+
38
+ ## Componentes
39
+
40
+ ### Button (Ações)
41
+
42
+ Botão de ação com texto.
43
+ - `contained` (padrão): fundo cheio na cor primary. Ação comum.
44
+ - `outlined`: borda cinza. Ação secundária ao lado da principal.
45
+ - `text`: sem borda nem fundo. Ação discreta (cancelar, ver mais).
46
+ - `gradient`: chamada principal da marca. No máximo um por tela.
47
+ - `gradientOutlined`: borda e texto em gradiente. Destaque secundário.
48
+
49
+ Ao clicar, mostra uma onda a partir do ponto do clique. Com `loading`, mantém a cor e a largura e mostra um spinner no lugar do texto.
50
+ Não use para ação só com ícone (use IconButton) nem para navegar para outra página (use TextLink).
51
+
52
+
53
+ Exemplo:
54
+
55
+ ```tsx
56
+ <Button variant="gradient" onClick={salvar}>Salvar</Button>
57
+ ```
58
+
59
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/ações-button--docs
60
+
61
+ Props:
62
+
63
+ - `backgroundColor` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Background color using theme color tokens (e.g. 'primary', 'secondary', 'error')
64
+ - `borderRadius` (`string`): Border radius as CSS value (e.g. '4px', '50%')
65
+ - `children` (`ReactNode`): Content to render inside the button
66
+ - `color` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Text color using theme color tokens (e.g. 'primary', 'secondary', 'error')
67
+ - `disabled` (`boolean`): Whether the button is disabled
68
+ - `fontSize` (`string`): Font size as CSS value (e.g. '14px', '1rem')
69
+ - `height` (`string`): Height as CSS value (e.g. '40px', '3rem')
70
+ - `loading` (`boolean`): When true, shows a loading spinner and disables the button
71
+ - `onClick` (`((e: MouseEvent<HTMLButtonElement, MouseEvent>) => void)`): Click event handler
72
+ - `padding` (`string`): Padding as CSS value (e.g. '8px 16px')
73
+ - `size` (`sm` | `md` | `lg` | `small`): Tamanho pronto: altura, espaçamento interno e fonte. Sem `size`, o botão usa os valores de sempre (ou os que vierem em `height`, `padding` e `fontSize`, que sempre têm prioridade). - `sm` - 40px, para tabelas, filtros e cards - `md` - 44px, padrão de formulários - `lg` - 52px, para destaque em telas vazias e landing `'small'` (da v1) é aceito por compatibilidade e não muda o tamanho.
74
+ - `textTransform` (`none` | `uppercase` | `capitalize` | `lowercase`): Text transform style
75
+ - `title` (`string`): Tooltip text displayed on hover
76
+ - `variant` (`gradient` | `contained` | `outlined` | `text` | `gradientOutlined`): Visual style variant of the button - `contained` - filled background (default) - `outlined` - transparent background with border - `text` - no background or border - `gradient` - fundo no gradiente da marca, texto branco. Ação principal da tela (CTA). - `gradientOutlined` - borda e texto no gradiente da marca, fundo branco. Ação secundária de destaque.
77
+ - `width` (`string`): Width as CSS value (e.g. '100%', '200px')
78
+
79
+ ### IconButton (Ações)
80
+
81
+ Botão só com ícone, para ações curtas e repetidas (editar, excluir, fechar, mais opções).
82
+ `label` é obrigatório: é o nome que o leitor de tela anuncia e o texto ao passar o mouse.
83
+ Para a ação principal da tela use Button.
84
+
85
+
86
+ Exemplo:
87
+
88
+ ```tsx
89
+ <IconButton icon="delete_bin7" label="Excluir arquivo" variant="outlined" color="error" />
90
+ ```
91
+
92
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/ações-iconbutton--docs
93
+
94
+ Props:
95
+
96
+ - `icon` (`IconsName`, valores em lib/ai/icons.txt, obrigatória): Ícone do botão.
97
+ - `label` (`string`, obrigatória): O que o botão faz, para leitor de tela e tooltip do navegador (ex. "Excluir arquivo"). Obrigatório.
98
+ - `color` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Cor do ícone e da borda no `outlined`. Sem ela, ícone `grey_2` e borda `grey_4`. Ignorada nas variantes de gradiente.
99
+ - `size` (`sm` | `md` | `lg`, padrão `md`): Tamanho.
100
+ - `variant` (`gradient` | `outlined` | `gradientOutlined` | `ghost`, padrão `ghost`): Estilo do botão.
101
+
102
+ ### Card (Cards)
103
+
104
+ Superfície que agrupa um bloco de conteúdo. O `elevated` (padrão) é o card branco com sombra
105
+ das telas e dashboards; o `outlined` só tem contorno e serve para agrupar itens dentro dele.
106
+ `gradientBorder` põe a borda no gradiente da marca (fixa ou `'animated'`, girando).
107
+ Aceita as props do Box para ajustar espaçamento e tamanho.
108
+ Para título com ícone use TitleCard; para número de dashboard use StatCard.
109
+
110
+
111
+ Exemplo:
112
+
113
+ ```tsx
114
+ <Card gap={2}>
115
+ <TitleCard icon="file_list3" title="Fornecedores" description="Busca e gestão" />
116
+ </Card>
117
+ ```
118
+
119
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/cards-card--docs
120
+
121
+ Props:
122
+
123
+ - `alignItems` (`center` | `flex-start` | `flex-end` | `stretch`): Flex align-items alignment
124
+ - `backgroundColor` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Background color using theme color tokens (e.g. 'primary', 'grey_1')
125
+ - `border` (`BorderProps | null`): Border configuration — pass `null` to remove border
126
+ - `borderColor` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Cor da borda (token). Padrão: `grey_5` no `elevated`, `grey_4` no `outlined`.
127
+ - `borderRadius` (`"sm" | "md" | "lg" | "none" | "xl" | "2xl" | (string & Record<never, never>) | "full"`): Arredondamento: nome do token (`none`, `sm` 4px, `md` 8px, `lg` 12px, `xl` 16px, `2xl` 24px, `full`), preferido em código novo, ou valor CSS (ex. `'50%'`).
128
+ - `borderWidth` (`number`, padrão `1 (2 na borda animada)`): Grossura da borda em px, em qualquer tipo de card.
129
+ - `boxShadow` (`"focus" | "sm" | "md" | "lg" | "xs" | "xl" | (string & Record<never, never>)`): Sombra: nome do token (`xs`, `sm`, `md`, `lg`, `xl`, `focus`), preferido em código novo, ou valor CSS.
130
+ - `children` (`ReactNode`): Conteúdo do card.
131
+ - `cursor` (`text` | `none` | `cell` | `copy` | `move` | `crosshair` | `grab` | `pointer` | `default` | `auto` | `context-menu` | `help` | `progress` | `wait` | `vertical-text` | `alias` | `no-drop` | `not-allowed` | `grabbing` | `all-scroll` | `col-resize` | `row-resize` | `n-resize` | `e-resize` | `s-resize` | `w-resize` | `ne-resize` | `nw-resize` | `se-resize` | `sw-resize` | `ew-resize` | `ns-resize` | `nesw-resize` | `nwse-resize` | `zoom-in` | `zoom-out`): CSS cursor property
132
+ - `direction` (`row` | `column` | `row-reverse` | `column-reverse`): Flex direction
133
+ - `flex` (`number | "none" | (string & Record<never, never>)`): CSS `flex`. Número para crescer (`1` ocupa o espaço que sobra) ou `'none'` para manter o tamanho e não encolher (use em ícones, botões e marcadores de tamanho fixo ao lado de texto).
134
+ - `flexWrap` (`wrap` | `nowrap` | `wrap-reverse`): Flex wrap behavior
135
+ - `gap` (`SizeType`): Gap between children using theme spacing scale (0-10)
136
+ - `gradientBorder` (`boolean | "animated"`): Borda no gradiente da marca. - `true`: borda fixa (1px por padrão), no ângulo da logo. Para destacar um card (recomendação, resultado de IA). - `'animated'`: borda (2px por padrão) com as cores da marca girando devagar. Para algo em andamento ou que pede atenção (análise rodando, novidade). Use um por tela; quem pediu menos movimento no sistema vê a borda parada. Ignora `borderColor`.
137
+ - `height` (`string`): Height as CSS value
138
+ - `justifyContent` (`center` | `flex-start` | `flex-end` | `space-between` | `space-around` | `space-evenly`): Flex justify-content alignment
139
+ - `margin` (`SizeType`): Margin on all sides using theme spacing scale (0-10)
140
+ - `marginBottom` (`SizeType`): Bottom margin using theme spacing scale (0-10)
141
+ - `marginLeft` (`SizeType`): Left margin using theme spacing scale (0-10)
142
+ - `marginRight` (`SizeType`): Right margin using theme spacing scale (0-10)
143
+ - `marginTop` (`SizeType`): Top margin using theme spacing scale (0-10)
144
+ - `marginX` (`SizeType`): Horizontal margin (left + right) using theme spacing scale (0-10)
145
+ - `marginY` (`SizeType`): Vertical margin (top + bottom) using theme spacing scale (0-10)
146
+ - `maxHeight` (`string`): Max height as CSS value
147
+ - `maxWidth` (`string`): Max width as CSS value
148
+ - `minHeight` (`string`): Min height as CSS value
149
+ - `minWidth` (`string`): Min width as CSS value
150
+ - `order` (`number`): CSS order property for flex children
151
+ - `overflow` (`hidden` | `scroll` | `auto` | `visible`): CSS overflow behavior
152
+ - `padding` (`SizeType`): Padding on all sides using theme spacing scale (0-10)
153
+ - `paddingBottom` (`SizeType`): Bottom padding using theme spacing scale (0-10)
154
+ - `paddingLeft` (`SizeType`): Left padding using theme spacing scale (0-10)
155
+ - `paddingRight` (`SizeType`): Right padding using theme spacing scale (0-10)
156
+ - `paddingTop` (`SizeType`): Top padding using theme spacing scale (0-10)
157
+ - `paddingX` (`SizeType`): Horizontal padding (left + right) using theme spacing scale (0-10)
158
+ - `paddingY` (`SizeType`): Vertical padding (top + bottom) using theme spacing scale (0-10)
159
+ - `position` (`absolute` | `relative` | `static` | `fixed` | `sticky`): CSS position property
160
+ - `variant` (`outlined` | `elevated`, padrão `elevated`): Visual do card.
161
+ - `width` (`string`): Width as CSS value (e.g. '100%', '300px')
162
+
163
+ ### StatCard (Cards)
164
+
165
+ Card de indicador das dashboards: ícone, título, número grande e descrição.
166
+ Use para um número que a pessoa acompanha (total, percentual, pendências).
167
+ Para bloco com conteúdo livre use Card + TitleCard.
168
+
169
+
170
+ Exemplo:
171
+
172
+ ```tsx
173
+ <StatCard icon="box3" title="Total de produtos" value="32" description="Produtos cadastrados na plataforma" />
174
+ ```
175
+
176
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/cards-statcard--docs
177
+
178
+ Props:
179
+
180
+ - `icon` (`IconsName`, valores em lib/ai/icons.txt, obrigatória): Ícone do indicador, numa caixinha com o gradiente da marca.
181
+ - `title` (`string`, obrigatória): Nome do indicador (ex. "Total de produtos").
182
+ - `customContent` (`ReactNode`): Conteúdo no lugar do número (ex. um gráfico pequeno).
183
+ - `description` (`string`): Texto de apoio abaixo do número (até 3 linhas).
184
+ - `descriptionMinLines` (`number`): Reserva altura para N linhas de descrição, para alinhar cards lado a lado.
185
+ - `height` (`string`): Altura do card (valor CSS). Use `'100%'` para igualar a altura numa linha de cards.
186
+ - `infoLabel` (`string`, padrão `Mais informações`): Texto do botão de informação para leitores de tela.
187
+ - `loading` (`boolean`): Mostra um esqueleto no lugar do número enquanto carrega.
188
+ - `onInfoClick` (`(() => void)`): Quando presente, mostra um botão de informação no canto do card.
189
+ - `secondaryValue` (`string`): Complemento ao lado do número (ex. "de 120", "kg CO₂e"). Deixa o número um pouco menor.
190
+ - `testId` (`string`): `data-testid` do conteúdo do card, para testes.
191
+ - `value` (`string`): Número principal.
192
+
193
+ ### TitleCard (Cards)
194
+
195
+ Cabeçalho de card: ícone em caixa, título, descrição e um elemento opcional à direita.
196
+ Use no topo de um Card para nomear o bloco. Para número de dashboard use StatCard.
197
+
198
+
199
+ Exemplo:
200
+
201
+ ```tsx
202
+ <TitleCard icon="group" title="Fornecedores" description="Busca e gestão" element={<Button>Adicionar</Button>} />
203
+ ```
204
+
205
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/cards-titlecard--docs
206
+
207
+ Props:
208
+
209
+ - `icon` (`IconsName`, valores em lib/ai/icons.txt, obrigatória): Ícone do bloco, mostrado numa caixinha (IconBox) com o gradiente da marca.
210
+ - `description` (`string`): Texto de apoio abaixo do título.
211
+ - `descriptionIcon` (`IconsName`, valores em lib/ai/icons.txt): Ícone pequeno antes da descrição.
212
+ - `element` (`ReactNode`): Conteúdo à direita do título (botão, filtro, link). Quebra para baixo quando falta espaço.
213
+ - `nowrap` (`boolean`): Mantém título e `element` na mesma linha, cortando o título se faltar espaço.
214
+ - `title` (`string`): Título do bloco.
215
+
216
+ ### Calendar (Dados)
217
+
218
+ Calendário do mês com eventos marcados por bolinhas coloridas (ex.: auditorias agendadas, prazos de envio).
219
+ Setas trocam o mês; clicar num dia com eventos abre um balão com a lista (ou o conteúdo de `renderDayDetails`).
220
+ Até `maxEventsPerDay` bolinhas por dia, o resto vira "+N".
221
+ Não busca dados: quem usa passa `events` já montados. Para escolher uma data num formulário use um campo de data.
222
+
223
+
224
+ Exemplo:
225
+
226
+ ```tsx
227
+ <Calendar
228
+ events={[{ id: '1', date: '2026-10-21', label: 'Auditoria Fornecedor A', color: 'warning' }]}
229
+ legend={[{ label: 'Agendada', color: 'warning' }]}
230
+ />
231
+ ```
232
+
233
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/dados-calendar--docs
234
+
235
+ Props:
236
+
237
+ - `defaultMonth` (`Date`, padrão `hoje`): Mês mostrado ao abrir, quando o calendário controla o próprio mês.
238
+ - `events` (`CalendarEvent[]`, padrão `[]`): Eventos do calendário. Vários eventos no mesmo dia viram várias bolinhas.
239
+ - `labels` (`CalendarLabels`): Textos fixos, para tradução.
240
+ - `legend` (`CalendarLegendItem[]`): Legenda das cores, abaixo da grade.
241
+ - `locale` (`string`, padrão `pt-BR`): Idioma dos nomes de mês e dia da semana (código do navegador, ex. `en`, `es`, `zh`).
242
+ - `maxEventsPerDay` (`number`, padrão `3`): Quantas bolinhas aparecem por dia antes do "+N".
243
+ - `month` (`Date`): Mês mostrado (controlado). Use junto com `onMonthChange`.
244
+ - `onDayClick` (`((date: Date, events: CalendarEvent[]) => void)`): Chamado ao clicar num dia que tem eventos.
245
+ - `onMonthChange` (`((month: Date) => void)`): Chamado ao trocar de mês pelas setas, com o primeiro dia do novo mês.
246
+ - `renderDayDetails` (`((date: Date, events: CalendarEvent[]) => ReactNode)`): Conteúdo do balão que abre ao clicar num dia com eventos. Sem esta prop, o balão lista os eventos do dia (bolinha + nome). Retorne `null` para não abrir balão.
247
+ - `weekStartsOn` (`0` | `1`, padrão `0`): Primeiro dia da semana: 0 = domingo, 1 = segunda.
248
+
249
+ ### CanvasButton (Dados)
250
+
251
+ Botão compacto de vidro fosco para ações sobre um canvas (exportar PNG, isolar ramo, limpar seleção).
252
+
253
+
254
+ Exemplo:
255
+
256
+ ```tsx
257
+ <CanvasButton label="Exportar PNG" icon="download" onClick={exportar} />
258
+ ```
259
+
260
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/dados-árvore-canvascontrols--docs
261
+
262
+ Props:
263
+
264
+ - `label` (`string`, obrigatória): Texto do botão.
265
+ - `onClick` (`() => void`, obrigatória): Ação do botão.
266
+ - `disabled` (`boolean`): Desabilita o botão.
267
+ - `icon` (`IconsName`, valores em lib/ai/icons.txt): Ícone depois do texto.
268
+
269
+ ### CanvasPanel (Dados)
270
+
271
+ Painel de vidro fosco para agrupar controles sobre um canvas (árvore, mapa, gráfico grande).
272
+
273
+
274
+ Exemplo:
275
+
276
+ ```tsx
277
+ <CanvasPanel><DirectionToggle value={dir} onChange={setDir} /></CanvasPanel>
278
+ ```
279
+
280
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/dados-árvore-canvascontrols--docs
281
+
282
+ Props:
283
+
284
+ - `children` (`ReactNode`, obrigatória): Controles agrupados no painel.
285
+
286
+ ### DirectionToggle (Dados)
287
+
288
+ Chave Horizontal/Vertical para a direção de uma árvore. Ligada = vertical (`TB`).
289
+
290
+
291
+ Exemplo:
292
+
293
+ ```tsx
294
+ <DirectionToggle value={direction} onChange={setDirection} />
295
+ ```
296
+
297
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/dados-árvore-canvascontrols--docs
298
+
299
+ Props:
300
+
301
+ - `onChange` (`(value: TreeDirection) => void`, obrigatória): Chamado com a nova direção.
302
+ - `value` (`TB` | `LR`, obrigatória): Direção atual: `TB` vertical, `LR` horizontal.
303
+ - `labels` (`{ horizontal?: string; vertical?: string; } | undefined`, padrão `{ horizontal: 'Horizontal', vertical: 'Vertical' }`): Textos, para tradução.
304
+
305
+ ### FullscreenToggle (Dados)
306
+
307
+ Botão quadrado de vidro fosco para entrar e sair da tela cheia.
308
+
309
+
310
+ Exemplo:
311
+
312
+ ```tsx
313
+ <FullscreenToggle active={cheia} onChange={setCheia} />
314
+ ```
315
+
316
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/dados-árvore-canvascontrols--docs
317
+
318
+ Props:
319
+
320
+ - `active` (`boolean`, obrigatória): Se a tela cheia está ligada.
321
+ - `onChange` (`(active: boolean) => void`, obrigatória): Chamado com o novo estado.
322
+ - `labels` (`{ enter?: string; exit?: string; } | undefined`, padrão `{ enter: 'Tela cheia', exit: 'Sair da tela cheia' }`): Textos, para tradução.
323
+
324
+ ### InfoItem (Dados)
325
+
326
+ Par rótulo + valor das telas de detalhe (CNPJ, endereço, responsável). Sem valor, mostra "--".
327
+ Coloque vários lado a lado num Box com `flexWrap="wrap"` e `gap`.
328
+ Para número em destaque de dashboard use StatCard.
329
+
330
+
331
+ Exemplo:
332
+
333
+ ```tsx
334
+ <InfoItem label="CNPJ" value="12.345.678/0001-90" />
335
+ ```
336
+
337
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/dados-infoitem--docs
338
+
339
+ Props:
340
+
341
+ - `label` (`string`, obrigatória): Nome do dado (ex. "CNPJ", "Data de cadastro").
342
+ - `emptyText` (`string`, padrão `--`): O que aparece quando não há valor.
343
+ - `icon` (`IconsName`, valores em lib/ai/icons.txt): Ícone à esquerda, para listas de dados com ícone.
344
+ - `minWidth` (`string`, padrão `150px`): Largura mínima, para alinhar vários itens lado a lado (valor CSS).
345
+ - `value` (`ReactNode`): Valor do dado. Texto vazio, `null` ou `undefined` mostra `emptyText`. Aceita conteúdo próprio (Tag, link).
346
+
347
+ ### Matrix (Dados)
348
+
349
+ Matriz de linhas × colunas com itens nas células: matriz de riscos (probabilidade × impacto),
350
+ materialidade, grade de status por mês ou valores por mês.
351
+ A Matrix cuida da grade, dos títulos, da legenda e do clique; a tela diz o que vai em cada célula
352
+ (`cellContent`, `renderCell`) e a cor (`getCellStyle`, com `getBand` para faixas).
353
+ - `variant="fill"`: células coladas e pintadas inteiras (riscos, materialidade).
354
+ - `variant="chip"`: selos com espaço entre eles (status ou valor por mês). Use `columnWidth` fixo para rolar na horizontal.
355
+
356
+ Para comparar números entre categorias use BarChart; para dados em lista use Table.
357
+
358
+
359
+ Exemplo:
360
+
361
+ ```tsx
362
+ <Matrix
363
+ aria-label="Matriz de riscos"
364
+ rows={[5, 4, 3, 2, 1].map((key) => ({ key, label: key }))}
365
+ columns={[1, 2, 3, 4, 5].map((key) => ({ key, label: key }))}
366
+ items={riscos}
367
+ getCellStyle={({ row, column }) => ({ background: getBand(+row.key * +column.key, faixas)?.color })}
368
+ legend={faixas}
369
+ />
370
+ ```
371
+
372
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/dados-matrix--docs
373
+
374
+ Props:
375
+
376
+ - `aria-label` (`string`, obrigatória): Nome da matriz para leitores de tela (ex. "Matriz de riscos").
377
+ - `columns` (`MatrixAxisItem[]`, obrigatória): Colunas, da esquerda para a direita.
378
+ - `rows` (`MatrixAxisItem[]`, obrigatória): Linhas, de cima para baixo.
379
+ - `cellContent` (`none` | `count` | `dots`, padrão `count`): O que aparece dentro da célula quando não há `renderCell`. - `count`: número de itens num círculo branco (vazio quando 0). - `dots`: uma bolinha por item, com a cor e o nome do item. - `none`: nada.
380
+ - `cellHeight` (`string`, padrão `'64px' com `fill`, '34px' com `chip``): Altura de cada linha (valor CSS).
381
+ - `columnAxisLabel` (`string`): Título do eixo das colunas, embaixo (ex. "Impacto").
382
+ - `columnWidth` (`string`, padrão `minmax(48px, 1fr)`): Largura de cada coluna (valor CSS). Com valor fixo, a matriz rola na horizontal quando não cabe.
383
+ - `getCellLabel` (`((cell: MatrixCell<T>) => string)`, padrão `'<linha> × <coluna>: N itens'`): Nome da célula para leitores de tela.
384
+ - `getCellStyle` (`((cell: MatrixCell<T>) => MatrixCellStyle)`): Fundo e cor do texto de cada célula. Sem esta prop, a célula fica no fundo do card.
385
+ - `isCellHighlighted` (`((cell: MatrixCell<T>) => boolean)`): Destaca a célula com um fundo levemente roxo (ex. zona material). Na legenda, use `highlighted`.
386
+ - `items` (`T[]`, padrão `[]`): Itens; cada um cai na célula de `row` × `column`.
387
+ - `legend` (`MatrixLegendItem[]`): Legenda abaixo da matriz.
388
+ - `legendInfoLabel` (`((label: string) => string)`, padrão `(label) => `Sobre ${label}``): Nome do botão (i) da legenda para leitores de tela; recebe o nome do item.
389
+ - `onCellClick` (`((cell: MatrixCell<T>) => void)`): Chamado ao clicar numa célula com itens.
390
+ - `renderCell` (`((cell: MatrixCell<T>) => ReactNode)`): Conteúdo próprio da célula (ex. selo de status, valor em reais). Substitui `cellContent`.
391
+ - `renderCellDetails` (`((cell: MatrixCell<T>) => ReactNode)`): Conteúdo do balão ao clicar numa célula com itens. Sem esta prop, a célula não é clicável.
392
+ - `rowAxisLabel` (`string`): Título do eixo das linhas, na vertical à esquerda (ex. "Probabilidade").
393
+ - `rowHeaderWidth` (`string`, padrão `120px`): Largura da coluna de cabeçalhos das linhas (valor CSS).
394
+ - `variant` (`chip` | `fill`, padrão `fill`): Formato das células. - `fill`: células coladas, cada uma pintada inteira (matriz de riscos, materialidade). - `chip`: selos arredondados com espaço entre eles (grade de envios, valores por mês).
395
+
396
+ ### Pagination (Dados)
397
+
398
+ Paginação de listas e tabelas. Um componente só, em duas formas:
399
+ - com `total` (número de páginas): só as setas e os números de página;
400
+ - com `totalItems` (número de itens): o rodapé completo de tabela, com itens por página,
401
+ páginas e a contagem ("20 de 78"). As páginas saem de `totalItems` e `itemsPerPage`.
402
+ Os textos (`viewText`, `itemsText`, `ofText`) podem ser traduzidos.
403
+
404
+ Nomes antigos que ainda funcionam: TablePagination.
405
+
406
+ Exemplo:
407
+
408
+ ```tsx
409
+ <Pagination total={10} current={pagina} onChange={setPagina} />
410
+ ```
411
+
412
+ Exemplo:
413
+
414
+ ```tsx
415
+ <Pagination totalItems={240} onChange={setPagina} onChangeItemsPerPage={setPorPagina} />
416
+ ```
417
+
418
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/dados-table-pagination--docs
419
+
420
+ Props:
421
+
422
+ - `current` (`number`, padrão `1`): Página atual (começa em 1).
423
+ - `itemsPerPage` (`number`, padrão `10`): Itens por página (só com `totalItems`).
424
+ - `itemsPerPageOptions` (`number[]`, padrão `[10, 50, 100]`): Quantidades oferecidas no seletor de itens por página (só com `totalItems`).
425
+ - `itemsText` (`string`, padrão `itens`): Texto depois da quantidade no seletor ("10 itens").
426
+ - `ofText` (`string`, padrão `de`): Texto da contagem ("20 de 78").
427
+ - `onChange` (`((page: number) => void)`): Chamado ao trocar de página, com o número da página.
428
+ - `onChangeItemsPerPage` (`((itemsPerPage: number) => void)`): Chamado ao trocar a quantidade de itens por página, com o novo valor.
429
+ - `showAll` (`boolean`): Mostra todos os números de página, sem reticências.
430
+ - `total` (`number`): Número de páginas. Use quando a lista já sabe quantas páginas tem. Com `totalItems`, as páginas são calculadas e este valor é ignorado.
431
+ - `totalItems` (`number`): Número de itens da lista. Liga o rodapé completo: itens por página à esquerda, páginas no meio e a contagem ("20 de 78") à direita.
432
+ - `viewText` (`string`, padrão `Visualizar`): Texto antes do seletor de itens por página.
433
+
434
+ ### SelectableItem (Dados)
435
+
436
+ Linha selecionável de uma lista (ex. dentro do SidePanel). Selecionada, ganha borda no gradiente da marca.
437
+
438
+
439
+ Exemplo:
440
+
441
+ ```tsx
442
+ <SelectableItem selected={ativo} onClick={escolher}>Camiseta básica</SelectableItem>
443
+ ```
444
+
445
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/dados-árvore-sidepanel--docs
446
+
447
+ Props:
448
+
449
+ - `children` (`ReactNode`, obrigatória): Conteúdo da linha.
450
+ - `onClick` (`() => void`, obrigatória): Chamado ao escolher a linha.
451
+ - `disabled` (`boolean`): Desabilita a linha.
452
+ - `selected` (`boolean`, padrão `false`): Linha selecionada: borda no gradiente da marca.
453
+
454
+ ### SidePanel (Dados)
455
+
456
+ Painel lateral com uma lista que conversa com o conteúdo ao lado (ex. itens ao lado da árvore de rastreabilidade).
457
+ Tem título, busca, rolagem própria, rodapé (paginação) e pode recolher para uma faixa de 40px.
458
+ Use SelectableItem em cada linha. Para menu de navegação da aplicação use a sidebar do app.
459
+
460
+
461
+ Exemplo:
462
+
463
+ ```tsx
464
+ <SidePanel title="Itens" search={{ value: busca, onChange: setBusca }}>
465
+ {itens.map((item) => <SelectableItem key={item.id} selected={item.id === atual} onClick={() => setAtual(item.id)}>{item.nome}</SelectableItem>)}
466
+ </SidePanel>
467
+ ```
468
+
469
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/dados-árvore-sidepanel--docs
470
+
471
+ Props:
472
+
473
+ - `children` (`ReactNode`, obrigatória): Lista (use SelectableItem para cada linha).
474
+ - `title` (`string`, obrigatória): Título do painel (ex. "Itens rastreados").
475
+ - `collapsed` (`boolean`): Painel recolhido (controlado). Sem esta prop, o painel guarda o estado sozinho.
476
+ - `collapsible` (`boolean`, padrão `true`): Mostra o botão de recolher o painel para uma faixa de 40px.
477
+ - `description` (`string`): Texto de apoio abaixo do título.
478
+ - `footer` (`ReactNode`): Conteúdo fixo no fim do painel (ex. Pagination).
479
+ - `labels` (`{ collapse?: string; expand?: string; clearSearch?: string | undefined; } | undefined`, padrão `{ collapse: 'Esconder lista', expand: 'Mostrar lista', clearSearch: 'Limpar busca' }`): Textos, para tradução.
480
+ - `onCollapsedChange` (`((collapsed: boolean) => void)`): Chamado ao recolher ou abrir.
481
+ - `search` (`{ value: string; onChange: (value: string) => void; placeholder?: string; label?: string; } | undefined`): Campo de busca acima da lista.
482
+ - `width` (`string`, padrão `320px`): Largura do painel aberto (valor CSS).
483
+
484
+ ### Table (Dados)
485
+
486
+ Tabela de dados com colunas configuráveis (`headers`), seleção de linhas (`selectable`) e conteúdo próprio por coluna (`customRender`).
487
+ No celular, `mobileLayout="cards"` mostra cada linha como um card.
488
+ `onRowClick` deixa a linha clicável (com destaque no hover e teclado); `hoverable` só destaca.
489
+ Para listas grandes, coloque `<Pagination totalItems={...} />` abaixo.
490
+
491
+
492
+ Exemplo:
493
+
494
+ ```tsx
495
+ <Table headers={[{ key: 'nome', label: 'Nome' }]} data={fornecedores} />
496
+ ```
497
+
498
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/dados-table-table--docs
499
+
500
+ Props:
501
+
502
+ - `data` (`TableData[]`, obrigatória): Array of row data objects
503
+ - `headers` (`TableHeader[]`, obrigatória): Array of column header configurations
504
+ - `borderRadius` (`string`): Border radius as CSS value (e.g. '8px')
505
+ - `boxShadow` (`string`): Box shadow as CSS value
506
+ - `footer` (`ReactNode`): Custom content rendered below the table (e.g. pagination)
507
+ - `header` (`ReactNode`): Custom content rendered above the table (e.g. filters, search)
508
+ - `hoverable` (`boolean`, padrão `true quando há `onRowClick``): Destaca a linha no hover mesmo sem `onRowClick`.
509
+ - `mobileLayout` (`scroll` | `cards`, padrão `scroll`): Como a tabela fica no celular (até 768px). - `scroll` (padrão): igual ao desktop, com rolagem horizontal. - `cards`: cada linha vira um card, com o nome da coluna ao lado do valor e sem cabeçalho. Use em listas que as pessoas consultam no celular.
510
+ - `onRowClick` (`((row: TableData, index: number) => void)`): Torna cada linha clicável (ex. abrir o detalhe do fornecedor): destaque no hover, cursor de mão, Tab chega na linha e Enter ou espaço abrem. Cliques em botões, links e no checkbox dentro da linha não disparam.
511
+ - `onSelectionChange` (`((selected: TableData[]) => void)`): Called when the selection changes — receives the updated selected rows array
512
+ - `selectable` (`boolean`): Whether rows can be selected (shows checkboxes)
513
+ - `selected` (`TableData[]`): Array of currently selected rows (controlled mode)
514
+ - `spacing` (`small` | `normal`): Row spacing density - `normal` — standard padding - `small` — compact padding
515
+
516
+ ### Tag (Dados)
517
+
518
+ Etiqueta curta de status (aprovado, pendente, em análise).
519
+ Use para o estado de um item em lista, tabela ou card, com as cores de estado
520
+ (`success`, `warning`, `error`, `info`). Não espalhe etiquetas coloridas pela tela
521
+ nem use como botão principal (use Button) ou contador de aba (use `badge` do Tabs).
522
+
523
+
524
+ Exemplo:
525
+
526
+ ```tsx
527
+ <Tag label="Aprovado" color="success" showDot />
528
+ ```
529
+
530
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/dados-tag--docs
531
+
532
+ Props:
533
+
534
+ - `label` (`string`, obrigatória): Texto da etiqueta.
535
+ - `ariaLabel` (`string`): Rótulo para leitor de tela quando o texto curto não basta.
536
+ - `backgroundColor` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Cor do fundo, quando diferente do fundo claro gerado a partir de `color`.
537
+ - `borderColor` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Cor da borda, quando diferente de `color`.
538
+ - `className` (`string`): Classe CSS, para usar com `styled(Tag)`.
539
+ - `color` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors), padrão `'grey_3'`): Cor da etiqueta (token): pinta texto, borda e um fundo claro da mesma cor. Use as cores de estado (`success`, `warning`, `error`, `info`) para status.
540
+ - `data-testid` (`string`): `data-testid` do elemento raiz, para testes.
541
+ - `dotColor` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Cor do ponto, quando precisa ser diferente da cor do texto e da borda (ex.: etiqueta cinza com ponto verde de "atualizado").
542
+ - `dotOutlineColor` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors), padrão `'grey_1'`): Cor do anel em volta do ponto (com `dotOutlined`).
543
+ - `dotOutlined` (`boolean`, padrão `false`): Desenha um anel escuro no ponto. Uma cor clara sozinha não alcança 3:1 num ponto de 8px sobre fundo claro; o anel dá a borda que falta.
544
+ - `gradient` (`boolean`, padrão `false`): Borda, texto e ícones no gradiente da marca, sem fundo.
545
+ - `icon` (`IconsName`, valores em lib/ai/icons.txt): Ícone antes do texto.
546
+ - `iconRight` (`string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | null`): Ícone (nome) ou elemento depois do texto.
547
+ - `loading` (`boolean`, padrão `false`): Mostra um spinner no lugar do ícone da direita e ignora cliques (ex. "3 fornecedores" enquanto o próximo nível carrega).
548
+ - `onClick` (`((event: MouseEvent<Element, MouseEvent> | KeyboardEvent<Element>) => void)`): Torna a etiqueta clicável (e acessível por teclado). Recebe o evento para que quem usa possa parar a propagação, quando a etiqueta está dentro de outra área clicável.
549
+ - `showDot` (`boolean`, padrão `false`): Mostra um ponto de status antes do texto.
550
+ - `width` (`string`): Largura (valor CSS). Padrão: o tamanho do texto.
551
+
552
+ ### Timeline (Dados)
553
+
554
+ Linha do tempo vertical com marcadores, para histórico de eventos em ordem (envios, mudanças de status).
555
+ `status` em cada item pinta feito (verde), em andamento (roxo) e pendente (cinza); `variant="compact"` usa bolinhas, para dentro de cards.
556
+
557
+
558
+ Exemplo:
559
+
560
+ ```tsx
561
+ <Timeline items={eventos} />
562
+ ```
563
+
564
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/dados-timeline--docs
565
+
566
+ Props:
567
+
568
+ - `items` (`Omit<TimelineItemProps, "index">[]`, obrigatória): Array of timeline items to render (index is set automatically)
569
+ - `variant` (`compact` | `numbered`, padrão `'numbered'`): Visual de todos os itens: `numbered` (círculo numerado) ou `compact` (bolinha, para dentro de cards).
570
+
571
+ ### TintedSection (Dados)
572
+
573
+ Seção dentro de um card: título colorido, um elemento opcional à direita e o conteúdo numa caixa com fundo tingido da mesma cor.
574
+ Use para agrupar informações de um tipo dentro de um card maior (ex. "Processo produtivo" e "Transporte" num nó da árvore).
575
+ Para aviso que precisa chamar atenção use Alert.
576
+
577
+
578
+ Exemplo:
579
+
580
+ ```tsx
581
+ <TintedSection tone="chart.lilac" title="Processo produtivo" aside={<Tag label="3/5" color="primary" />}>
582
+ PRC-0042 · Tinturaria
583
+ </TintedSection>
584
+ ```
585
+
586
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/dados-tintedsection--docs
587
+
588
+ Props:
589
+
590
+ - `title` (`ReactNode`, obrigatória): Título da seção (ex. "Processo produtivo").
591
+ - `tone` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors), obrigatória): Cor da seção (token): pinta o título e um fundo de 8% na caixa do conteúdo.
592
+ - `aside` (`ReactNode`): Elemento à direita do título (ex. uma Tag "3/5 etapas").
593
+ - `children` (`ReactNode`): Conteúdo da seção. Sem conteúdo, mostra só o título.
594
+ - `divider` (`boolean`, padrão `true`): Linha divisória acima da seção, para separar do que vem antes no card.
595
+
596
+ ### TreeNode (Dados)
597
+
598
+ Cartão de um nó de árvore (rastreabilidade de itens, fornecedores, processos, transportes).
599
+ Traz categoria com bolinha, botão de detalhes no canto, botão de adicionar origem na borda de saída e rodapé.
600
+ Use `TreeNode.Title` e `TreeNode.Caption` para os textos dentro dele.
601
+ Os conectores e o canvas (React Flow) ficam fora: este é só o cartão que vai dentro de cada nó.
602
+
603
+
604
+ Exemplo:
605
+
606
+ ```tsx
607
+ <TreeNode category={{ label: 'Tecelagem', color: 'chart.purple' }} add={{ label: 'Adicionar origem', onClick: abrir }}>
608
+ <TreeNode.Title>Tecelagem Norte Ltda.</TreeNode.Title>
609
+ <TreeNode.Caption>Blumenau - SC</TreeNode.Caption>
610
+ </TreeNode>
611
+ ```
612
+
613
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/dados-árvore-treenode--docs
614
+
615
+ Props:
616
+
617
+ - `children` (`ReactNode`, obrigatória): Conteúdo do nó (título, legendas, etiquetas).
618
+ - `add` (`{ label: string; onClick: () => void; }`): Botão redondo de "adicionar" na borda de saída do nó, para criar a próxima origem.
619
+ - `aria-label` (`string`): Nome do nó para leitores de tela e teclado (ex. "Tecelagem Norte, tecido plano"). Nome do nó para leitores de tela.
620
+ - `category` (`{ label: ReactNode; color: string; }`): Rótulo de categoria no topo, com bolinha colorida (ex. segmento da empresa).
621
+ - `categoryAside` (`ReactNode`): Elemento à direita da categoria (ex. CNPJ).
622
+ - `details` (`{ label: string; onClick?: (() => void); href?: string; icon?: IconsName | undefined; } | undefined`): Botão de detalhes no canto superior direito. Com `href`, vira link.
623
+ - `direction` (`TB` | `LR`, padrão `TB`): Direção da árvore: decide em que borda fica o botão de adicionar.
624
+ - `emphasis` (`none` | `dimmed` | `highlighted`, padrão `none`): Destaque em relação aos outros nós. - `dimmed`: apagado (fora do filtro ou do ramo em foco). - `highlighted`: anel roxo (corresponde ao filtro).
625
+ - `footer` (`ReactNode`): Rodapé do nó (ex. evidências e origens).
626
+ - `gradientBorder` (`boolean`, padrão `false`): Borda no gradiente da marca (ex. etapa em andamento).
627
+ - `onClick` (`(() => void)`): Chamado ao clicar no nó (fora dos botões). Exige `aria-label`.
628
+ - `variant` (`default` | `root` | `declaration`, padrão `default`): Tipo do nó. - `default`: cartão branco. - `root`: nó de partida, com borda roxa de 2px. - `declaration`: origem declarada (sem documento), com borda tracejada roxa e fundo levemente roxo.
629
+ - `width` (`string`, padrão `280px`): Largura do cartão (valor CSS).
630
+
631
+ ### TreeView (Dados)
632
+
633
+ Árvore que abre e fecha para mostrar um objeto aninhado (ex.: dados de um certificado ou resposta de API).
634
+ `openAll` já abre tudo.
635
+
636
+ Nomes antigos que ainda funcionam: Treeview.
637
+
638
+ Exemplo:
639
+
640
+ ```tsx
641
+ <TreeView obj={dados} openAll />
642
+ ```
643
+
644
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/dados-treeview--docs
645
+
646
+ Props:
647
+
648
+ - `obj` (`any`, obrigatória): The object to render as a tree structure
649
+ - `openAll` (`boolean`): When true, all nested nodes start expanded
650
+ - `tab` (`number`, padrão `0`): Base indentation level (number of tabs from the left)
651
+
652
+ ### Alert (Feedback)
653
+
654
+ Caixa de aviso fixa na tela, com ícone e fundo claro do tipo (informação, sucesso, alerta, erro).
655
+ Use para avisos que precisam ficar visíveis: campo obrigatório faltando, documento vencido, regra da tela.
656
+ Para aviso passageiro depois de uma ação use Toast; para status de um item use Tag.
657
+
658
+
659
+ Exemplo:
660
+
661
+ ```tsx
662
+ <Alert status="warning" title="Documento vencido">Envie a nova licença até 30/10.</Alert>
663
+ ```
664
+
665
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/feedback-alert--docs
666
+
667
+ Props:
668
+
669
+ - `action` (`ReactNode`): Ação à direita (ex. um Button `text` "Ver detalhes"). Botões e links aqui usam a cor do texto.
670
+ - `children` (`ReactNode`): Texto do aviso. Pode ter links ou listas.
671
+ - `closeLabel` (`string`, padrão `Fechar aviso`): Nome do botão de fechar para leitores de tela.
672
+ - `icon` (`IconsName`, valores em lib/ai/icons.txt): Troca o ícone padrão do tipo.
673
+ - `onClose` (`(() => void)`): Quando presente, mostra o botão de fechar.
674
+ - `status` (`info` | `success` | `error` | `warning`, padrão `info`): Tipo do aviso.
675
+ - `title` (`string`): Título curto em negrito, acima do texto.
676
+
677
+ ### EmptyState (Feedback)
678
+
679
+ O que aparece quando uma lista, tabela ou tela não tem nada para mostrar.
680
+ A versão completa explica o vazio e oferece uma ação; a `compact` é só o texto, para painéis.
681
+ Com `state="loading"` ou `state="error"` cobre também o carregando e o erro de uma área inteira (ex. canvas de árvore);
682
+ `minHeight` faz ocupar a altura dela. Para lista ou card carregando, prefira Skeleton.
683
+
684
+
685
+ Exemplo:
686
+
687
+ ```tsx
688
+ <EmptyState icon="group" title="Nenhum fornecedor ainda" description="Cadastre o primeiro para começar." action={<Button>Adicionar fornecedor</Button>} />
689
+ ```
690
+
691
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/feedback-emptystate--docs
692
+
693
+ Props:
694
+
695
+ - `action` (`ReactNode`): Ação para sair do vazio (ex. um Button "Adicionar fornecedor"). Ignorada no `compact`.
696
+ - `compact` (`boolean`, padrão `false`): Versão mínima: só o texto centralizado em cinza, para painéis e listas pequenas (ex. "Nenhuma notificação").
697
+ - `description` (`string`): Texto explicando o que fazer ou por que está vazio.
698
+ - `icon` (`IconsName`, valores em lib/ai/icons.txt): Ícone, numa caixinha com o gradiente da marca. Ignorado no `compact`.
699
+ - `minHeight` (`string`): Altura mínima, para ocupar a área do conteúdo (ex. o canvas de uma árvore, `'560px'`).
700
+ - `state` (`loading` | `error` | `empty`, padrão `empty`): Situação da área: - `empty` (padrão): nada para mostrar. - `loading`: spinner no lugar do ícone, enquanto os dados chegam. - `error`: ícone de alerta em vermelho; use `action` para "Tentar de novo".
701
+ - `title` (`string`): Título curto (ex. "Nenhum fornecedor ainda"). Ignorado no `compact`.
702
+
703
+ ### ProgressBar (Feedback)
704
+
705
+ Barra que mostra quanto de uma tarefa já foi feito (questionário respondido, homologação, upload).
706
+ O preenchimento usa o gradiente da marca; `color` troca por uma cor do tema (ex. `success`).
707
+ Para espera sem porcentagem conhecida use Spinner ou Skeleton.
708
+
709
+
710
+ Exemplo:
711
+
712
+ ```tsx
713
+ <ProgressBar value={60} label="Questionário" showValue />
714
+ ```
715
+
716
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/feedback-progressbar--docs
717
+
718
+ Props:
719
+
720
+ - `value` (`number`, obrigatória): Quanto já foi feito, de 0 a 100. Valores fora disso são limitados.
721
+ - `aria-label` (`string`): Nome para leitores de tela quando não há `label`.
722
+ - `color` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Cor do preenchimento (token). Sem valor, usa o gradiente da marca.
723
+ - `label` (`string`): Texto acima da barra (ex. "Questionário"). Também vira o nome para leitores de tela.
724
+ - `showValue` (`boolean`, padrão `false`): Mostra a porcentagem à direita do rótulo.
725
+ - `size` (`sm` | `md`, padrão `md`): Espessura: `sm` 4px, `md` 8px.
726
+
727
+ ### Skeleton (Feedback)
728
+
729
+ Bloco cinza com brilho que ocupa o lugar de um conteúdo enquanto ele carrega.
730
+ Use em lista, card e número carregando; para ação curta (salvar, enviar) use Spinner.
731
+
732
+
733
+ Exemplo:
734
+
735
+ ```tsx
736
+ <Skeleton width="50px" height="42px" />
737
+ ```
738
+
739
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/feedback-skeleton--docs
740
+
741
+ Props:
742
+
743
+ - `borderRadius` (`string`, padrão `sm`): Arredondamento: token (`sm`, `md`, `lg`, `full`…) ou valor CSS.
744
+ - `className` (`string`): Classe CSS, para usar com `styled(Skeleton)`.
745
+ - `height` (`string`, padrão `20px`): Altura (valor CSS).
746
+ - `width` (`string`, padrão `100%`): Largura (valor CSS).
747
+
748
+ ### Spinner (Feedback)
749
+
750
+ Indicador circular de carregamento.
751
+ Use em ação curta (botão salvando, bloco carregando). Para lista ou card carregando, prefira um esqueleto (Skeleton).
752
+ Por padrão é um arco fino (`arc`); `variant="gradient"` usa as cores da marca e `variant="classic"` é o anel grosso da v1.
753
+ Anuncia "Carregando" para leitores de tela; troque com `label`.
754
+
755
+
756
+ Exemplo:
757
+
758
+ ```tsx
759
+ <Spinner size="24px" variant="gradient" />
760
+ ```
761
+
762
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/feedback-spinner--docs
763
+
764
+ Props:
765
+
766
+ - `color` (`ThemeColors | "currentColor"`, valores em 58 valores possíveis): Cor do spinner: token do tema ou `currentColor` (cor do texto em volta). Não vale no `gradient`.
767
+ - `label` (`string`, padrão `Carregando`): Texto lido por leitores de tela enquanto carrega.
768
+ - `size` (`string`): Spinner size as CSS value (e.g. '24px', '2rem')
769
+ - `variant` (`gradient` | `arc` | `classic`, padrão `'arc'`): Visual do spinner. - `arc`: arco fino que some na cauda; a grossura acompanha o tamanho. Use `color="currentColor"` para seguir o texto. - `gradient`: arco nas cores da marca (roxo → teal). Para carregamentos de destaque (análise, IA, relatório). - `classic`: anel grosso (5px) com uma abertura, o visual da v1.
770
+
771
+ ### Toast (Feedback)
772
+
773
+ Aviso temporário no canto da tela (salvou, falhou, atenção). Controlado: mostre com `show`
774
+ e esconda em `onClose`, que é chamado ao fim de `duration` ou no botão de fechar.
775
+ Uma mensagem nova com o aviso aberto não apaga a anterior: as duas ficam empilhadas.
776
+ Para mensagem de campo use `message` do Input; para aviso fixo na página use outro bloco.
777
+
778
+
779
+ Exemplo:
780
+
781
+ ```tsx
782
+ <Toast show={saved} type="success" message="Fornecedor salvo" onClose={() => setSaved(false)} />
783
+ ```
784
+
785
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/feedback-toast--docs
786
+
787
+ Props:
788
+
789
+ - `children` (`ReactNode`): Conteúdo no lugar do texto (ex. texto + link).
790
+ - `duration` (`number`, padrão `5000`): Tempo em ms até `onClose` ser chamado. Use `0` para não fechar sozinho.
791
+ - `message` (`string`): Texto do aviso.
792
+ - `onClose` (`(() => void)`): Chamado ao fim de `duration` e no botão de fechar (que só aparece quando há `onClose`).
793
+ - `position` (`top-left` | `top-right` | `bottom-left` | `bottom-right`, padrão `bottom-left`): Canto da tela.
794
+ - `show` (`boolean`, padrão `false`): Mostra o aviso.
795
+ - `type` (`info` | `success` | `error` | `warning`, padrão `success`): Tipo do aviso.
796
+ - `usePortal` (`boolean`, padrão `true`): Abre no canto da tela, empilhado com outros avisos. Com `false`, aparece onde foi colocado.
797
+
798
+ ### Tooltip (Feedback)
799
+
800
+ Texto curto que aparece ao passar o mouse ou focar um elemento, para explicar um ícone ou um termo.
801
+ Com `clickable`, abre e fecha no clique (bom para celular e textos para ler com calma).
802
+ Não deixe informação essencial só no tooltip, porque no celular não existe "passar o mouse".
803
+ Para conteúdo maior ou com botões use Popover.
804
+
805
+
806
+ Exemplo:
807
+
808
+ ```tsx
809
+ <Tooltip title="Exportar CSV"><IconButton icon="download" label="Exportar" /></Tooltip>
810
+ ```
811
+
812
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/feedback-tooltip--docs
813
+
814
+ Props:
815
+
816
+ - `children` (`ReactNode`, obrigatória): Element that triggers the tooltip on hover
817
+ - `title` (`string`, obrigatória): Text content displayed inside the tooltip
818
+ - `clickable` (`boolean`, padrão `false`): Abre e fecha no clique, em vez de passar o mouse. Fecha também ao clicar fora ou com Esc. Use quando o texto precisa ficar aberto para ler com calma ou no celular, onde não existe hover.
819
+ - `disabled` (`boolean`): Whether to disable the tooltip
820
+ - `offset` (`number`, padrão `10`): Distance in pixels between the tooltip and the trigger element
821
+ - `placement` (`left` | `right` | `top` | `bottom`, padrão `'top'`): Lado em que o tooltip aparece. Se não couber na tela, troca para o lado oposto (e depois para os outros).
822
+
823
+ ### Autocomplete (Formulários)
824
+
825
+ Campo de texto com sugestões, para escolher uma ou várias opções de uma lista longa (fornecedores, países).
826
+ A busca pode ser local ou no servidor (`isAsync` + `onFilterChange`); `multiple` permite várias escolhas.
827
+ Para poucas opções fixas use Select.
828
+
829
+
830
+ Exemplo:
831
+
832
+ ```tsx
833
+ <Autocomplete label="Fornecedor" options={opcoes} onChange={setFornecedor} />
834
+ ```
835
+
836
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/formulários-autocomplete--docs
837
+
838
+ Props:
839
+
840
+ - `borderColor` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Cor da borda (token do tema, ex. 'success', 'primary'). Sem ela, a borda é cinza e fica vermelha no estado `error`; sucesso e alerta só mudam a mensagem. O anel de foco segue esta cor.
841
+ - `disabled` (`boolean`, padrão `false`): Whether the field is disabled
842
+ - `getOptionLabel` (`((option: AutocompleteOption) => string)`): Function to extract the display label from an option object. Required when options don't have a `label` property. @example (option) => option.name
843
+ - `icon` (`IconsName`, valores em lib/ai/icons.txt): Icon name displayed inside the input (from the Icon component)
844
+ - `isAsync` (`boolean`): When true, enables async mode — the component calls `onFilterChange` on every keystroke and expects the parent to update `options`. Use `loading` to show a spinner while fetching.
845
+ - `label` (`ReactNode`): Label text displayed above the input
846
+ - `limitTags` (`number`): Maximum number of selected tags to display when `multiple` is true. Additional selections are shown as "+N"
847
+ - `loading` (`boolean`): Whether to show a loading spinner (useful with `isAsync`)
848
+ - `message` (`string`): Helper or error message displayed below the input
849
+ - `multiple` (`boolean`): When true, allows selecting multiple options (value becomes an array)
850
+ - `noOptionsText` (`string`, padrão `'No options'`): Text displayed when the options list is empty
851
+ - `onChange` (`((value?: AutocompleteOption | AutocompleteOption[]) => void)`): Called when the selection changes — receives the selected value(s)
852
+ - `onFilterChange` (`((value: string) => void)`): Called on every keystroke with the current filter text (useful with `isAsync`)
853
+ - `options` (`AutocompleteOption[]`): List of options to display in the dropdown. Can be any kind of objects — if the object has no `label` property, provide a `getOptionLabel` function.
854
+ - `placeholder` (`string`): Placeholder text when no value is selected
855
+ - `required` (`boolean`, padrão `false`): Whether the field is required
856
+ - `state` (`success` | `error` | `warning` | `default`, padrão `default`): Validation state that changes the border color and icon
857
+ - `value` (`AutocompleteOption | AutocompleteOption[]`): Selected value(s) — single object or array when `multiple` is true
858
+ - `width` (`string`, padrão `100%`): Width as CSS value (e.g. '100%', '300px')
859
+
860
+ ### Checkbox (Formulários)
861
+
862
+ Caixa de marcar, para sim/não ou para escolher vários itens de uma lista.
863
+ `align` alinha a caixa com a primeira linha (`start`), o centro (`center`) ou a última linha (`end`) do texto.
864
+ Para ligar ou desligar algo que vale na hora, sem salvar, use Switch.
865
+ `variant="gradient"` usa borda e ✓ no gradiente da marca, com fundo branco.
866
+
867
+ Nomes antigos que ainda funcionam: CheckBox.
868
+
869
+ Exemplo:
870
+
871
+ ```tsx
872
+ <Checkbox label="Aceito os termos" checked={aceito} onChange={(e) => setAceito(e.target.checked)} />
873
+ ```
874
+
875
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/formulários-checkbox--docs
876
+
877
+ Props:
878
+
879
+ - `align` (`end` | `start` | `center`, padrão `center`): Alinhamento do quadradinho em relação ao rótulo. - `start`: na altura do texto da primeira linha. Use quando o rótulo puder ter várias linhas. - `center`: no meio do bloco de texto. - `end`: na altura do texto da última linha.
880
+ - `borderColor` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Cor da borda (token do tema, ex. 'success', 'primary'). Sem ela, a borda é cinza e fica vermelha no estado `error`; sucesso e alerta só mudam a mensagem. O anel de foco segue esta cor.
881
+ - `checked` (`boolean`): Whether the checkbox is checked
882
+ - `color` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Checkbox color using theme color tokens (e.g. 'primary', 'secondary')
883
+ - `disabled` (`boolean`, padrão `false`): Whether the checkbox is disabled
884
+ - `label` (`string`): Label text displayed next to the checkbox
885
+ - `message` (`string`): Helper or error message displayed below the checkbox
886
+ - `name` (`string`): Name attribute for the input element (used in forms)
887
+ - `onChange` (`((event: ChangeEvent<HTMLInputElement>) => void)`): Change event handler
888
+ - `required` (`boolean`): Whether the field is required
889
+ - `size` (`number`, padrão `16`): Size of the checkbox in pixels
890
+ - `state` (`success` | `error` | `warning` | `default`, padrão `default`): Validation state that changes the visual style
891
+ - `variant` (`gradient` | `default`, padrão `default`): Visual da caixa. - `default`: borda cinza; marcada, fica cheia na cor `color` (padrão primary) com ✓ branco. - `gradient`: borda e ✓ no gradiente da marca, fundo sempre branco (o checkbox de gradiente do front).
892
+
893
+ ### DatePicker (Formulários)
894
+
895
+ Campo de data: dá para digitar (com máscara no formato do idioma) ou escolher no calendário.
896
+ O valor é `AAAA-MM-DD`, igual ao `<input type="date">`, então a troca no front não muda a API.
897
+ No calendário: setas andam pelos dias, PageUp/PageDown trocam o mês, Enter escolhe, Esc fecha.
898
+ Para período (de/até) use DateRangePicker; para só mês e ano use MonthPicker.
899
+
900
+
901
+ Exemplo:
902
+
903
+ ```tsx
904
+ <DatePicker label="Vencimento" value={vencimento} onChange={setVencimento} min="2026-01-01" />
905
+ ```
906
+
907
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/formulários-datas-datepicker--docs
908
+
909
+ Props:
910
+
911
+ - `defaultValue` (`string`, padrão ``): Data inicial quando o campo guarda a data sozinho.
912
+ - `disabled` (`boolean`): Desabilita o campo.
913
+ - `label` (`string`): Rótulo acima do campo.
914
+ - `labels` (`DatePickerLabels`): Textos fixos, para tradução.
915
+ - `locale` (`string`, padrão `pt-BR`): Idioma do formato da data e dos nomes de mês (ex. `en`, `es`).
916
+ - `max` (`string`): Data máxima que pode ser escolhida (`AAAA-MM-DD`).
917
+ - `message` (`string`): Mensagem abaixo do campo (erro, ajuda).
918
+ - `min` (`string`): Data mínima que pode ser escolhida (`AAAA-MM-DD`).
919
+ - `name` (`string`): Nome do campo no formulário.
920
+ - `onChange` (`((value: string) => void)`): Chamado com a nova data (`AAAA-MM-DD`) ou `''` ao limpar.
921
+ - `required` (`boolean`): Marca o campo como obrigatório.
922
+ - `state` (`success` | `error` | `warning` | `default`, padrão `default`): Estado do campo; `error` pinta a borda e a mensagem de vermelho.
923
+ - `value` (`string`): Data escolhida, `AAAA-MM-DD` (igual ao `<input type="date">`). Vazio = sem data. Sem esta prop, o campo guarda a data sozinho.
924
+ - `weekStartsOn` (`0` | `1`, padrão `0`): Primeiro dia da semana no calendário: 0 = domingo, 1 = segunda.
925
+ - `width` (`string`, padrão `100%`): Largura (valor CSS).
926
+
927
+ ### DateRangePicker (Formulários)
928
+
929
+ Período de/até: dois campos para digitar e um calendário para escolher.
930
+ No calendário, o primeiro clique marca o início e o segundo o fim; o período aparece pintado enquanto o mouse passa.
931
+ `presets` mostra atalhos ao lado (ex. "Últimos 7 dias").
932
+ As datas são `AAAA-MM-DD`; uma das pontas pode ficar vazia (só "a partir de" ou só "até").
933
+ Para uma data só use DatePicker.
934
+
935
+
936
+ Exemplo:
937
+
938
+ ```tsx
939
+ <DateRangePicker label="Período" value={periodo} onChange={setPeriodo} presets={[{ label: 'Últimos 7 dias', range: ultimos7 }]} />
940
+ ```
941
+
942
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/formulários-datas-daterangepicker--docs
943
+
944
+ Props:
945
+
946
+ - `defaultValue` (`DateRange`, padrão `{}`): Período inicial quando o campo guarda o período sozinho.
947
+ - `disabled` (`boolean`): Desabilita o campo.
948
+ - `label` (`string`): Rótulo acima dos dois campos (ex. "Período de envio").
949
+ - `labels` (`DatePickerLabels`): Textos fixos, para tradução.
950
+ - `locale` (`string`, padrão `pt-BR`): Idioma do formato da data e dos nomes de mês (ex. `en`, `es`).
951
+ - `max` (`string`): Data máxima que pode ser escolhida (`AAAA-MM-DD`).
952
+ - `message` (`string`): Mensagem abaixo do campo (erro, ajuda).
953
+ - `min` (`string`): Data mínima que pode ser escolhida (`AAAA-MM-DD`).
954
+ - `onChange` (`((value: DateRange) => void)`): Chamado com o novo período.
955
+ - `presets` (`DateRangePreset[]`): Atalhos ao lado do calendário.
956
+ - `required` (`boolean`): Marca o campo como obrigatório.
957
+ - `state` (`success` | `error` | `warning` | `default`, padrão `default`): Estado do campo; `error` pinta a borda e a mensagem de vermelho.
958
+ - `value` (`DateRange`): Período escolhido. Sem esta prop, o campo guarda o período sozinho.
959
+ - `weekStartsOn` (`0` | `1`, padrão `0`): Primeiro dia da semana no calendário: 0 = domingo, 1 = segunda.
960
+ - `width` (`string`, padrão `100%`): Largura (valor CSS).
961
+
962
+ ### FileDropzone (Formulários)
963
+
964
+ Área para arrastar ou escolher arquivos, com a lista dos enviados (`showPreview`) ou miniaturas (`showImage`).
965
+ Confere o tipo (`fileType`) e o tamanho (`maxSize`) e mostra a mensagem de erro.
966
+ `gradient` troca o roxo da borda e do ícone pelo gradiente da marca.
967
+
968
+ Nomes antigos que ainda funcionam: DragNDrop.
969
+
970
+ Exemplo:
971
+
972
+ ```tsx
973
+ <FileDropzone multiple showPreview fileType="application/pdf" onChange={setArquivos} />
974
+ ```
975
+
976
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/formulários-arquivos-filedropzone--docs
977
+
978
+ Props:
979
+
980
+ - `defaultFiles` (`string[]`): Array of URLs for pre-existing files (shown as default previews)
981
+ - `disabled` (`boolean`): Whether the file input is disabled
982
+ - `fileType` (`string`): Accepted file types (MIME types, e.g. 'image/*', 'application/pdf')
983
+ - `fileTypeError` (`string`): Custom error message shown when the file type is not accepted
984
+ - `gradient` (`boolean`, padrão `false`): Borda tracejada e ícone no gradiente da marca.
985
+ - `maxSize` (`number`): Maximum file size allowed in bytes
986
+ - `maxSizeError` (`string`): Custom error message shown when the file exceeds the max size
987
+ - `multiple` (`boolean`, padrão `false`): Whether to allow multiple file selection
988
+ - `name` (`string`): Name attribute for the file input element
989
+ - `onChange` (`((files?: File[]) => void)`): Called when files are selected or removed — receives the current file array
990
+ - `onDeleteDefaultFile` (`((index: number) => void)`): Called when a default (pre-existing) file is removed — receives the index
991
+ - `preview` (`list` | `image`, padrão `list`): Preview mode for selected files - `list` — shows files as a list with name and size - `image` — shows image thumbnails
992
+ - `showImage` (`boolean`, padrão `false`): Whether to show image thumbnails in list preview mode
993
+ - `showPreview` (`boolean`, padrão `true`): Whether to show a preview of selected files
994
+
995
+ ### FileImagePreview (Formulários)
996
+
997
+ Miniatura de uma imagem enviada (arquivo ou URL), com ações de trocar e excluir.
998
+ Arquivo que não é imagem aparece como ícone. Normalmente vem pronto dentro do FileDropzone (`preview="image"`).
999
+
1000
+
1001
+ Exemplo:
1002
+
1003
+ ```tsx
1004
+ <FileImagePreview file={foto} onDelete={remover} />
1005
+ ```
1006
+
1007
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/formulários-arquivos-filepreview--docs
1008
+
1009
+ Props:
1010
+
1011
+ - `file` (`string | File`, obrigatória): File object or URL string to preview as an image
1012
+ - `onChange` (`((file: File) => void)`): Called when the file is changed/replaced
1013
+ - `onClickInput` (`(() => void)`): Called when the image is clicked (e.g. to open a file picker)
1014
+ - `onDelete` (`(() => void)`): Called when the delete button is clicked
1015
+
1016
+ ### FileImagePreviewList (Formulários)
1017
+
1018
+ Grade de miniaturas das imagens enviadas, com excluir em cada uma. `defaultFiles` mostra imagens que já estavam salvas (URLs).
1019
+ Normalmente vem pronta dentro do FileDropzone com `multiple` e `preview="image"`.
1020
+
1021
+
1022
+ Exemplo:
1023
+
1024
+ ```tsx
1025
+ <FileImagePreviewList files={fotos} setFiles={setFotos} />
1026
+ ```
1027
+
1028
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/formulários-arquivos-filepreview--docs
1029
+
1030
+ Props:
1031
+
1032
+ - `files` (`File[]`, obrigatória): Array of selected File objects to preview as images
1033
+ - `defaultFiles` (`string[]`): Array of URLs for pre-existing files (shown as default previews)
1034
+ - `onDelete` (`((value: number[]) => void)`): Called when files are deleted — receives the array of removed indices
1035
+ - `onDeleteDefaultFile` (`((index: number) => void)`): Called when a default (pre-existing) file is removed — receives the index
1036
+ - `setFiles` (`((files: File[]) => void)`): Callback to update the files array (used when removing a file)
1037
+
1038
+ ### FilePreview (Formulários)
1039
+
1040
+ Linha de um arquivo enviado: ícone pelo tipo, nome, tamanho e ações (selecionar, excluir).
1041
+ O FileDropzone já usa esta peça; use direto quando a lista de arquivos vem de outro lugar.
1042
+
1043
+
1044
+ Exemplo:
1045
+
1046
+ ```tsx
1047
+ <FilePreview file={arquivo} onDelete={remover} />
1048
+ ```
1049
+
1050
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/formulários-arquivos-filepreview--docs
1051
+
1052
+ Props:
1053
+
1054
+ - `file` (`string | File`, obrigatória): File object or URL string to preview
1055
+ - `isSelected` (`boolean`): Whether the file is currently selected
1056
+ - `onChange` (`((file: File) => void)`): Called when the file is changed/replaced
1057
+ - `onClickInput` (`(() => void)`): Called when the preview is clicked (e.g. to open a file picker)
1058
+ - `onDelete` (`(() => void)`): Called when the delete button is clicked
1059
+ - `onSelect` (`(() => void)`): Called when the selection checkbox is toggled
1060
+ - `selectable` (`boolean`): Whether the file can be selected (shows a checkbox)
1061
+ - `showImage` (`boolean`): Whether to show an image thumbnail of the file
1062
+
1063
+ ### FilePreviewList (Formulários)
1064
+
1065
+ Lista dos arquivos enviados, com nome, ícone do tipo e excluir. `defaultFiles` mostra arquivos que já estavam salvos (URLs).
1066
+ Normalmente vem pronta dentro do FileDropzone com `multiple` e `preview="list"`.
1067
+
1068
+
1069
+ Exemplo:
1070
+
1071
+ ```tsx
1072
+ <FilePreviewList files={arquivos} setFiles={setArquivos} />
1073
+ ```
1074
+
1075
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/formulários-arquivos-filepreview--docs
1076
+
1077
+ Props:
1078
+
1079
+ - `files` (`File[]`, obrigatória): Array of selected File objects to preview
1080
+ - `defaultFiles` (`string[]`): Array of URLs for pre-existing files (shown as default previews)
1081
+ - `onDelete` (`((value: number[]) => void)`): Called when files are deleted — receives the array of removed indices
1082
+ - `onDeleteDefaultFile` (`((index: number) => void)`): Called when a default (pre-existing) file is removed — receives the index
1083
+ - `setFiles` (`((value: File[]) => void)`): Callback to update the files array (used when removing a file)
1084
+ - `showImages` (`boolean`, padrão `false`): Whether to show image thumbnails for each file
1085
+
1086
+ ### Input (Formulários)
1087
+
1088
+ Campo de texto de uma linha, com rótulo (`label`), mensagem abaixo (`message`) e estado (`state`: erro, sucesso, alerta).
1089
+ Rótulo e mensagem já ficam ligados ao campo para o leitor de tela.
1090
+ Para texto longo use TextArea; para escolher de uma lista use Select ou Autocomplete.
1091
+
1092
+
1093
+ Exemplo:
1094
+
1095
+ ```tsx
1096
+ <Input label="E-mail" state="error" message="E-mail inválido" />
1097
+ ```
1098
+
1099
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/formulários-input--docs
1100
+
1101
+ Props:
1102
+
1103
+ - `adornment` (`ReactNode`): Element rendered inside the input (e.g. icon, button)
1104
+ - `adornmentPosition` (`left` | `right`, padrão `right`): Position of the adornment element
1105
+ - `borderColor` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Cor da borda (token do tema, ex. 'success', 'primary'). Sem ela, a borda é cinza e fica vermelha no estado `error`; sucesso e alerta só mudam a mensagem. O anel de foco segue esta cor.
1106
+ - `boxProps` (`BoxProps`): Additional props passed to the wrapper Box component
1107
+ - `disabled` (`boolean`, padrão `false`): Whether the input is disabled
1108
+ - `label` (`string`): Label text displayed above the input
1109
+ - `mask` (`string`): Mask to be applied to the input value. - `0` — only numbers - `X` — any character @example '000.000.000-00' // CPF mask @example 'XXX.XXX.XXX-XX' // Alphanumeric mask
1110
+ - `message` (`string`): Helper or error message displayed below the input
1111
+ - `name` (`string`): Name attribute for the input element (used in forms)
1112
+ - `onChange` (`((e: ChangeEvent<HTMLInputElement>) => void)`): Change event handler
1113
+ - `placeholder` (`string`): Placeholder text when the input is empty
1114
+ - `required` (`boolean`, padrão `false`): Whether the field is required
1115
+ - `state` (`success` | `error` | `warning` | `default`, padrão `default`): Validation state that changes the border color and icon
1116
+ - `value` (`string`): Current input value
1117
+ - `width` (`string`, padrão `100%`): Width as CSS value (e.g. '100%', '300px')
1118
+
1119
+ ### MonthPicker (Formulários)
1120
+
1121
+ Campo para escolher mês e ano (ex.: competência de um envio).
1122
+ Abre um painel com o ano e os doze meses.
1123
+
1124
+
1125
+ Exemplo:
1126
+
1127
+ ```tsx
1128
+ <MonthPicker label="Competência" onChange={setCompetencia} />
1129
+ ```
1130
+
1131
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/formulários-datas-monthpicker--docs
1132
+
1133
+ Props:
1134
+
1135
+ - `disabled` (`boolean`): Whether the picker is disabled
1136
+ - `icon` (`IconsName`, valores em lib/ai/icons.txt, padrão `calendar`): Icon name displayed inside the input
1137
+ - `label` (`string`): Label text displayed above the picker
1138
+ - `onChange` (`((month?: number, year?: number) => void) | undefined`): Called when a month is selected — receives the month (1-12) and year
1139
+
1140
+ ### RadioGroup (Formulários)
1141
+
1142
+ Grupo de opções em que só uma pode ser marcada (ex. tipo de fornecedor, frequência de envio).
1143
+ Usa rádio nativo, então teclado e leitor de tela funcionam como em qualquer formulário.
1144
+ Para várias escolhas use Checkbox; para trocar a visualização na hora use ViewToggle;
1145
+ para mais de 6 opções use Select.
1146
+
1147
+
1148
+ Exemplo:
1149
+
1150
+ ```tsx
1151
+ <RadioGroup
1152
+ label="Frequência"
1153
+ value={frequencia}
1154
+ onChange={setFrequencia}
1155
+ options={[{ value: 'monthly', label: 'Mensal' }, { value: 'yearly', label: 'Anual' }]}
1156
+ />
1157
+ ```
1158
+
1159
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/formulários-radiogroup--docs
1160
+
1161
+ Props:
1162
+
1163
+ - `options` (`RadioOption<V>[]`, obrigatória): Opções; só uma pode ficar marcada.
1164
+ - `defaultValue` (`string`): Valor marcado ao abrir, quando o grupo guarda a escolha sozinho.
1165
+ - `direction` (`row` | `column`, padrão `column`): `column`: uma opção por linha. `row`: lado a lado, quebrando linha.
1166
+ - `disabled` (`boolean`, padrão `false`): Desabilita todas as opções.
1167
+ - `label` (`string`): Pergunta ou título do grupo, acima das opções.
1168
+ - `message` (`string`): Mensagem abaixo das opções (erro, ajuda).
1169
+ - `name` (`string`): Nome do grupo no formulário (atributo `name` dos inputs). Gerado quando não informado.
1170
+ - `onChange` (`((value: V) => void)`): Chamado ao marcar outra opção.
1171
+ - `required` (`boolean`): Marca as opções como obrigatórias (formulário nativo e leitores de tela).
1172
+ - `state` (`success` | `error` | `warning` | `default`, padrão `default`): Estado do grupo; `error` pinta as bolinhas e a mensagem de vermelho.
1173
+ - `value` (`string`): Valor marcado (controlado). Sem esta prop, o grupo guarda a escolha sozinho.
1174
+
1175
+ ### SearchInput (Formulários)
1176
+
1177
+ Campo de busca: ícone de lupa, espera a pessoa parar de digitar (`debounce`) e botão para limpar.
1178
+ `onChange` recebe cada letra; `onSearch` só recebe o texto final, então é nele que se chama a API.
1179
+ Para escolher um item de uma lista com sugestões use Autocomplete.
1180
+
1181
+
1182
+ Exemplo:
1183
+
1184
+ ```tsx
1185
+ <SearchInput placeholder="Buscar fornecedor" onSearch={setBusca} />
1186
+ ```
1187
+
1188
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/formulários-searchinput--docs
1189
+
1190
+ Props:
1191
+
1192
+ - `clearLabel` (`string`, padrão `Limpar busca`): Nome do botão de limpar para leitores de tela.
1193
+ - `debounce` (`number`, padrão `400`): Espera em ms depois da última letra antes de chamar `onSearch`.
1194
+ - `defaultValue` (`string`, padrão ``): Texto inicial quando o campo guarda o próprio texto.
1195
+ - `disabled` (`boolean`): Desabilita o campo.
1196
+ - `label` (`string`): Rótulo acima do campo. Sem rótulo, `placeholder` vira o nome para leitores de tela.
1197
+ - `onChange` (`((value: string) => void)`): Chamado a cada letra digitada, sem espera.
1198
+ - `onSearch` (`((value: string) => void)`): Chamado quando a pessoa para de digitar por `debounce` ms, e na hora ao limpar ou apertar Enter. É aqui que se busca.
1199
+ - `placeholder` (`string`, padrão `Buscar`): Texto de exemplo dentro do campo.
1200
+ - `value` (`string`): Texto da busca (controlado). Sem esta prop, o campo guarda o próprio texto.
1201
+ - `width` (`string`, padrão `100%`): Largura (valor CSS).
1202
+
1203
+ ### Select (Formulários)
1204
+
1205
+ Lista suspensa para escolher uma opção entre poucas (até umas 15).
1206
+ No celular abre o seletor nativo do sistema.
1207
+ Para lista longa ou com busca use Autocomplete.
1208
+
1209
+
1210
+ Exemplo:
1211
+
1212
+ ```tsx
1213
+ <Select label="Status" options={[{ value: 'ok', label: 'Aprovado' }]} onChange={setStatus} />
1214
+ ```
1215
+
1216
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/formulários-select--docs
1217
+
1218
+ Props:
1219
+
1220
+ - `borderColor` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Cor da borda (token do tema, ex. 'success', 'primary'). Sem ela, a borda é cinza e fica vermelha no estado `error`; sucesso e alerta só mudam a mensagem. O anel de foco segue esta cor.
1221
+ - `disabled` (`boolean`, padrão `false`): Whether the select is disabled
1222
+ - `label` (`string`): Label text displayed above the select
1223
+ - `message` (`string`): Helper or error message displayed below the select
1224
+ - `onChange` (`((e: ChangeEvent<HTMLInputElement>) => void)`): Change event handler — `e.target.value` contains the selected option value
1225
+ - `options` (`SelectOption[]`): Array of selectable options
1226
+ - `padding` (`string`): Padding as CSS value (e.g. '8px 16px')
1227
+ - `placeholder` (`string`): Placeholder text when no option is selected
1228
+ - `required` (`boolean`, padrão `false`): Whether the field is required
1229
+ - `state` (`success` | `error` | `warning` | `default`, padrão `default`): Validation state that changes the border color and icon
1230
+ - `value` (`string`): Currently selected value (must match one of the option values)
1231
+ - `variant` (`outlined` | `text`, padrão `outlined`): Visual style variant - `outlined` — with border (default) - `text` — no border, minimal style
1232
+ - `width` (`string`, padrão `100%`): Width as CSS value (e.g. '100%', '300px')
1233
+
1234
+ ### Switch (Formulários)
1235
+
1236
+ Chave liga/desliga para uma opção que vale na hora, sem botão salvar (ex.: notificações ativas).
1237
+ Ligada, o trilho fica no gradiente da marca; desligada, cinza. Três tamanhos (`size`).
1238
+ Para escolhas dentro de um formulário que será enviado use Checkbox.
1239
+
1240
+
1241
+ Exemplo:
1242
+
1243
+ ```tsx
1244
+ <Switch labelRight="Notificações" checked={ativo} onChange={(e) => setAtivo(e.target.checked)} />
1245
+ ```
1246
+
1247
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/formulários-switch--docs
1248
+
1249
+ Props:
1250
+
1251
+ - `checked` (`boolean`): Whether the switch is toggled on
1252
+ - `disabled` (`boolean`): Whether the switch is disabled
1253
+ - `labelLeft` (`string`): Label text displayed on the left side of the switch
1254
+ - `labelRight` (`string`): Label text displayed on the right side of the switch
1255
+ - `margin` (`string`): Margin as CSS value (e.g. '8px', '1rem 0')
1256
+ - `name` (`string`): Name attribute for the input element (used in forms)
1257
+ - `onChange` (`ChangeEventHandler<HTMLInputElement>`): Change event handler
1258
+ - `preventEvent` (`boolean`): When true, prevents the default change event from propagating
1259
+ - `size` (`sm` | `md` | `lg`, padrão `md`): Tamanho: `sm` 32×18, `md` 44×24, `lg` 56×30.
1260
+ - `textTransform` (`none` | `uppercase` | `capitalize` | `lowercase`): Text transform style for the labels
1261
+ - `value` (`string`): Value attribute for the input element
1262
+
1263
+ ### TextArea (Formulários)
1264
+
1265
+ Campo de texto de várias linhas, para comentários, justificativas e descrições.
1266
+ Tem o mesmo rótulo, mensagem e estado do Input.
1267
+
1268
+
1269
+ Exemplo:
1270
+
1271
+ ```tsx
1272
+ <TextArea label="Justificativa" rows={4} />
1273
+ ```
1274
+
1275
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/formulários-textarea--docs
1276
+
1277
+ Props:
1278
+
1279
+ - `borderColor` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Cor da borda (token do tema, ex. 'success', 'primary'). Sem ela, a borda é cinza e fica vermelha no estado `error`; sucesso e alerta só mudam a mensagem. O anel de foco segue esta cor.
1280
+ - `disabled` (`boolean`, padrão `false`): Whether the textarea is disabled
1281
+ - `label` (`string`): Label text displayed above the textarea
1282
+ - `message` (`string`): Helper or error message displayed below the textarea
1283
+ - `name` (`string`): Name attribute for the textarea element (used in forms)
1284
+ - `onChange` (`((e: ChangeEvent<HTMLTextAreaElement>) => void)`): Change event handler
1285
+ - `placeholder` (`string`): Placeholder text when the textarea is empty
1286
+ - `required` (`boolean`, padrão `false`): Whether the field is required
1287
+ - `rows` (`number`): Number of visible text rows
1288
+ - `state` (`success` | `error` | `warning` | `default`, padrão `default`): Validation state that changes the border color and icon
1289
+ - `value` (`string`): Current textarea value
1290
+ - `width` (`string`, padrão `100%`): Width as CSS value (e.g. '100%', '300px')
1291
+
1292
+ ### BarChart (Gráficos)
1293
+
1294
+ Gráfico de barras para comparar valores entre categorias (ex.: emissões por fornecedor).
1295
+ Cada item de `data` é uma barra, com `name` e `value`.
1296
+ Para evolução no tempo use LineChart; para partes de um total use DoughnutChart.
1297
+
1298
+
1299
+ Exemplo:
1300
+
1301
+ ```tsx
1302
+ <BarChart data={[{ name: 'Jan', value: 10 }, { name: 'Fev', value: 14 }]} />
1303
+ ```
1304
+
1305
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/gráficos-barchart--docs
1306
+
1307
+ Props:
1308
+
1309
+ - `data` (`BarChartData[]`, obrigatória): Array of data points to render as bars
1310
+ - `barCategoryGap` (`string | number`): Gap between bar categories in pixels or CSS string
1311
+ - `barSize` (`string | number`): Width of each bar in pixels or CSS string
1312
+ - `height` (`number`, padrão `300`): Chart height in pixels
1313
+ - `labelFormatter` (`((value: number) => string)`): Formatter function for bar labels (e.g. `(v) => \`${v} kg\``)
1314
+ - `radius` (`number | [number, number, number, number]`): Border radius of bars — single number or [topLeft, topRight, bottomRight, bottomLeft]
1315
+ - `showGrid` (`boolean`, padrão `true`): Whether to show the background grid lines
1316
+ - `showLabels` (`boolean`, padrão `false`): Whether to show value labels on top of each bar
1317
+ - `width` (`string | number`, padrão `100%`): Chart width as number (px) or CSS string (e.g. '100%')
1318
+ - `xAxisLabel` (`string`): Label for the X axis
1319
+ - `yAxisFormatter` (`((value: number) => string)`): Formatter function for Y axis tick values (e.g. `(v) => \`${v}%\``)
1320
+ - `yAxisLabel` (`string`): Label for the Y axis
1321
+
1322
+ ### ChartLegend (Gráficos)
1323
+
1324
+ Legenda de gráfico: bolinha na cor da série, nome e valor opcional.
1325
+ Use ao lado ou abaixo de qualquer gráfico; o DoughnutChart já monta a dele com a prop `legend`.
1326
+
1327
+
1328
+ Exemplo:
1329
+
1330
+ ```tsx
1331
+ <ChartLegend items={[{ label: 'Aprovados', color: 'success', value: '60%' }]} />
1332
+ ```
1333
+
1334
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/gráficos-chartlegend--docs
1335
+
1336
+ Props:
1337
+
1338
+ - `items` (`ChartLegendItem[]`, obrigatória): Itens da legenda, na ordem do gráfico.
1339
+ - `direction` (`row` | `column`, padrão `row`): `row`: itens lado a lado, quebrando linha. `column`: um por linha, com o valor alinhado à direita.
1340
+
1341
+ ### DoughnutChart (Gráficos)
1342
+
1343
+ Rosca que mostra partes de um total (ex.: 60% dos fornecedores aprovados).
1344
+ `parts` são as fatias; o que faltar para chegar em `totalValue` aparece em cinza.
1345
+ `legend` mostra a legenda das fatias com nome ao lado (`side`) ou abaixo (`bottom`).
1346
+ Use com até 5 fatias. Com mais categorias use BarChart.
1347
+
1348
+
1349
+ Exemplo:
1350
+
1351
+ ```tsx
1352
+ <DoughnutChart totalValue={100} parts={[{ value: 60, color: '#27AE60', name: 'Aprovados' }]} />
1353
+ ```
1354
+
1355
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/gráficos-doughnutchart--docs
1356
+
1357
+ Props:
1358
+
1359
+ - `parts` (`PartsProps[]`, obrigatória): Array of segments that compose the doughnut
1360
+ - `totalValue` (`number`, obrigatória): Total value used to calculate the percentage of each part
1361
+ - `backgroundColor` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Background color of the empty/remaining area using theme tokens
1362
+ - `customContent` (`ReactNode`): Custom React content to render in the center of the chart (overrides totalValue display)
1363
+ - `disableAnimation` (`boolean`, padrão `false`): Whether to disable the entrance animation
1364
+ - `fontSize` (`string`): Font size for the center text (CSS value, e.g. '16px')
1365
+ - `legend` (`side` | `bottom`): Mostra a legenda das fatias que têm `name`, ao lado (`side`) ou abaixo (`bottom`) da rosca.
1366
+ - `showTooltip` (`boolean`, padrão `false`): Whether to show a tooltip on hover over each segment
1367
+ - `showTotalValue` (`boolean`, padrão `true`): Whether to display the total value in the center of the chart
1368
+ - `size` (`number`, padrão `200`): Diameter of the chart in pixels
1369
+ - `tooltipValueFormatter` (`((value: number) => string)`): Formatter function for tooltip values (e.g. `(v) => \`${v}%\``)
1370
+
1371
+ ### LineChart (Gráficos)
1372
+
1373
+ Gráfico de linhas para mostrar evolução no tempo, com uma ou mais séries (`series`).
1374
+ `showArea` preenche a área abaixo da linha.
1375
+ Para comparar categorias sem ordem de tempo use BarChart.
1376
+
1377
+
1378
+ Exemplo:
1379
+
1380
+ ```tsx
1381
+ <LineChart data={dados} series={[{ dataKey: 'total', name: 'Total', color: '#6633CC' }]} />
1382
+ ```
1383
+
1384
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/gráficos-linechart--docs
1385
+
1386
+ Props:
1387
+
1388
+ - `data` (`LineChartData[]`, obrigatória): Array of data points
1389
+ - `series` (`LineChartSeries[]`, obrigatória): Array of line series configurations
1390
+ - `height` (`number`, padrão `300`): Chart height in pixels
1391
+ - `showArea` (`boolean`, padrão `false`): Whether to fill the area under the lines
1392
+ - `showGrid` (`boolean`, padrão `true`): Whether to show the background grid lines
1393
+ - `width` (`number`, padrão `500`): Chart width in pixels
1394
+ - `xAxisLabel` (`string`): Label for the X axis
1395
+ - `yAxisFormatter` (`((value: number) => string)`): Formatter function for Y axis tick values
1396
+ - `yAxisLabel` (`string`): Label for the Y axis
1397
+
1398
+ ### TreemapChart (Gráficos)
1399
+
1400
+ Retângulos com área proporcional ao valor, para mostrar o peso de muitas categorias de uma vez (ex.: volume por material).
1401
+ Para poucas categorias use BarChart ou DoughnutChart.
1402
+
1403
+
1404
+ Exemplo:
1405
+
1406
+ ```tsx
1407
+ <TreemapChart data={[{ name: 'Algodão', value: 120 }, { name: 'Poliéster', value: 40 }]} />
1408
+ ```
1409
+
1410
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/gráficos-treemapchart--docs
1411
+
1412
+ Props:
1413
+
1414
+ - `data` (`TreemapChartData[]`, obrigatória): Array of data points to render as treemap blocks
1415
+ - `height` (`number`, padrão `300`): Chart height in pixels
1416
+ - `valueFormatter` (`((value: number) => string)`): Formatter function for values shown inside blocks and in the tooltip
1417
+ - `width` (`string | number`, padrão `100%`): Chart width as number (px) or CSS string (e.g. '100%')
1418
+
1419
+ ### Avatar (Imagens e ícones)
1420
+
1421
+ Círculo com iniciais ou foto que representa uma pessoa ou empresa.
1422
+ Sem cor de texto, a letra fica branca ou escura conforme o fundo.
1423
+
1424
+
1425
+ Exemplo:
1426
+
1427
+ ```tsx
1428
+ <Avatar size="medium">SM</Avatar>
1429
+ ```
1430
+
1431
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/imagens-e-ícones-avatar--docs
1432
+
1433
+ Props:
1434
+
1435
+ - `backgroundColor` (`string`): Background color as CSS value (e.g. '#FF0000', 'rgb(0,0,0)')
1436
+ - `children` (`ReactNode`): Content rendered inside the avatar (text initials, icon, etc.)
1437
+ - `color` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Text color using theme color tokens. Sem valor, fica branco ou escuro conforme o fundo, para manter a leitura.
1438
+ - `fontSize` (`small` | `medium` | `normal` | `large`): Font size of the avatar content
1439
+ - `size` (`number | "small" | "medium" | "normal" | "large"`): Avatar size — predefined string or custom number in pixels - `small` — 24px - `normal` — 32px - `medium` — 40px - `large` — 48px
1440
+
1441
+ ### Icon (Imagens e ícones)
1442
+
1443
+ Ícone da biblioteca do DS pelo nome: ícones próprios da Blockforce, Remix e Lucide (`lu:nome`).
1444
+ `color` usa as cores do tema e `gradient` pinta com o gradiente da marca. A lista de nomes está em `lib/ai/icons.txt`.
1445
+ Para ícone clicável use IconButton; para ícone dentro de uma caixinha use IconBox.
1446
+
1447
+
1448
+ Exemplo:
1449
+
1450
+ ```tsx
1451
+ <Icon name="leaf" size={20} color="primary" />
1452
+ ```
1453
+
1454
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/imagens-e-ícones-icon--docs
1455
+
1456
+ Props:
1457
+
1458
+ - `name` (`IconsName`, valores em lib/ai/icons.txt, obrigatória): Icon name — can be a custom icon ('rocket', 'graph', 'receipt') or a RemixIcon name in snake_case
1459
+ - `color` (`string`): Icon color using theme color tokens or any CSS color value
1460
+ - `defs` (`ReactNode`): Custom SVG defs (e.g. gradients, patterns) to inject into the icon SVG
1461
+ - `fill` (`string`): SVG fill color (overrides color for specific paths)
1462
+ - `gradient` (`boolean`): Pinta o ícone com o gradiente da marca (secondary → primary do tema). Ignora `color`. Cada ícone ganha um id de gradiente próprio, então vários na mesma tela não se misturam.
1463
+ - `size` (`number`, padrão `24`): Icon size in pixels
1464
+
1465
+ ### IconBox (Imagens e ícones)
1466
+
1467
+ Ícone dentro de uma caixinha com borda e sombra leve. É o ícone dos títulos de card e dos números
1468
+ das dashboards. Sem `color`, o ícone vem no gradiente da marca.
1469
+ Use para identificar um bloco; não use como botão (use IconButton).
1470
+
1471
+
1472
+ Exemplo:
1473
+
1474
+ ```tsx
1475
+ <IconBox icon="file_list3" />
1476
+ ```
1477
+
1478
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/imagens-e-ícones-iconbox--docs
1479
+
1480
+ Props:
1481
+
1482
+ - `icon` (`IconsName`, valores em lib/ai/icons.txt, obrigatória): Ícone mostrado dentro da caixa.
1483
+ - `color` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Cor do ícone (token do tema). Sem ela, o ícone usa o gradiente da marca.
1484
+ - `size` (`number`, padrão `24`): Tamanho do ícone em px. A caixa acompanha (ícone + 10px de cada lado).
1485
+
1486
+ ### Image (Imagens e ícones)
1487
+
1488
+ Imagem com tamanho, cantos e ajuste (`objectFit`) controlados.
1489
+ `alt` é obrigatório: descreva a imagem, ou use `alt=""` se ela for só decoração.
1490
+
1491
+
1492
+ Exemplo:
1493
+
1494
+ ```tsx
1495
+ <Image src={logo} alt="Logo da empresa" maxHeight="40px" />
1496
+ ```
1497
+
1498
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/imagens-e-ícones-image--docs
1499
+
1500
+ Props:
1501
+
1502
+ - `alt` (`string`, obrigatória): Alt text for accessibility
1503
+ - `src` (`string`, obrigatória): Image source URL
1504
+ - `borderRadius` (`string`): Border radius as CSS value (e.g. '8px', '50%' for circular)
1505
+ - `height` (`string`): Height as CSS value (e.g. 'auto', '200px')
1506
+ - `maxHeight` (`string`): Max height as CSS value
1507
+ - `maxWidth` (`string`): Max width as CSS value
1508
+ - `objectFit` (`cover` | `fill` | `contain`): How the image should fit within its container - `fill` — stretches to fill (may distort) - `contain` — fits entirely, may leave empty space - `cover` — fills container, may crop
1509
+ - `width` (`string`): Width as CSS value (e.g. '100%', '200px')
1510
+
1511
+ ### Accordion (Layout)
1512
+
1513
+ Bloco que abre e fecha para mostrar detalhes sob demanda (perguntas frequentes, seções longas de formulário).
1514
+ `header` é a parte sempre visível.
1515
+ Para alternar entre visões do mesmo conteúdo use Tabs.
1516
+
1517
+
1518
+ Exemplo:
1519
+
1520
+ ```tsx
1521
+ <Accordion header={<Text>Detalhes</Text>}>Conteúdo</Accordion>
1522
+ ```
1523
+
1524
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/layout-accordion--docs
1525
+
1526
+ Props:
1527
+
1528
+ - `backgroundColor` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Background color using theme color tokens
1529
+ - `children` (`ReactNode`): Content rendered inside the collapsible body
1530
+ - `contentPadding` (`string`): Padding for the content area as CSS value (e.g. '16px', '1rem')
1531
+ - `header` (`ReactNode`): Content rendered in the accordion header (always visible)
1532
+ - `onToggle` (`((open: boolean) => void)`): Called when the accordion is toggled — receives the new open state
1533
+ - `open` (`boolean`, padrão `false`): Whether the accordion is expanded (controlled mode)
1534
+ - `renderCustomToggleIcon` (`((open: boolean) => ReactNode)`): Custom render function for the toggle icon — receives the current open state
1535
+ - `width` (`string`): Width as CSS value (e.g. '100%', '400px')
1536
+
1537
+ ### Box (Layout)
1538
+
1539
+ Bloco de layout em flexbox: direção, alinhamento, espaço entre itens (`gap`), padding e margem pela escala de espaço do tema.
1540
+ É a base de quase toda tela. Para superfície com fundo e sombra use Card.
1541
+
1542
+
1543
+ Exemplo:
1544
+
1545
+ ```tsx
1546
+ <Box direction="column" gap="md" padding="lg">...</Box>
1547
+ ```
1548
+
1549
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/layout-box--docs
1550
+
1551
+ Props:
1552
+
1553
+ - `alignItems` (`center` | `flex-start` | `flex-end` | `stretch`): Flex align-items alignment
1554
+ - `backgroundColor` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Background color using theme color tokens (e.g. 'primary', 'grey_1')
1555
+ - `border` (`BorderProps | null`): Border configuration — pass `null` to remove border
1556
+ - `borderRadius` (`"sm" | "md" | "lg" | "none" | "xl" | "2xl" | (string & Record<never, never>) | "full"`): Arredondamento: nome do token (`none`, `sm` 4px, `md` 8px, `lg` 12px, `xl` 16px, `2xl` 24px, `full`), preferido em código novo, ou valor CSS (ex. `'50%'`).
1557
+ - `boxShadow` (`"focus" | "sm" | "md" | "lg" | "xs" | "xl" | (string & Record<never, never>)`): Sombra: nome do token (`xs`, `sm`, `md`, `lg`, `xl`, `focus`), preferido em código novo, ou valor CSS.
1558
+ - `children` (`ReactNode`): Content rendered inside the box
1559
+ - `cursor` (`text` | `none` | `cell` | `copy` | `move` | `crosshair` | `grab` | `pointer` | `default` | `auto` | `context-menu` | `help` | `progress` | `wait` | `vertical-text` | `alias` | `no-drop` | `not-allowed` | `grabbing` | `all-scroll` | `col-resize` | `row-resize` | `n-resize` | `e-resize` | `s-resize` | `w-resize` | `ne-resize` | `nw-resize` | `se-resize` | `sw-resize` | `ew-resize` | `ns-resize` | `nesw-resize` | `nwse-resize` | `zoom-in` | `zoom-out`): CSS cursor property
1560
+ - `direction` (`row` | `column` | `row-reverse` | `column-reverse`): Flex direction
1561
+ - `flex` (`number | "none" | (string & Record<never, never>)`): CSS `flex`. Número para crescer (`1` ocupa o espaço que sobra) ou `'none'` para manter o tamanho e não encolher (use em ícones, botões e marcadores de tamanho fixo ao lado de texto).
1562
+ - `flexWrap` (`wrap` | `nowrap` | `wrap-reverse`): Flex wrap behavior
1563
+ - `gap` (`SizeType`): Gap between children using theme spacing scale (0-10)
1564
+ - `height` (`string`): Height as CSS value
1565
+ - `justifyContent` (`center` | `flex-start` | `flex-end` | `space-between` | `space-around` | `space-evenly`): Flex justify-content alignment
1566
+ - `margin` (`SizeType`): Margin on all sides using theme spacing scale (0-10)
1567
+ - `marginBottom` (`SizeType`): Bottom margin using theme spacing scale (0-10)
1568
+ - `marginLeft` (`SizeType`): Left margin using theme spacing scale (0-10)
1569
+ - `marginRight` (`SizeType`): Right margin using theme spacing scale (0-10)
1570
+ - `marginTop` (`SizeType`): Top margin using theme spacing scale (0-10)
1571
+ - `marginX` (`SizeType`): Horizontal margin (left + right) using theme spacing scale (0-10)
1572
+ - `marginY` (`SizeType`): Vertical margin (top + bottom) using theme spacing scale (0-10)
1573
+ - `maxHeight` (`string`): Max height as CSS value
1574
+ - `maxWidth` (`string`): Max width as CSS value
1575
+ - `minHeight` (`string`): Min height as CSS value
1576
+ - `minWidth` (`string`): Min width as CSS value
1577
+ - `order` (`number`): CSS order property for flex children
1578
+ - `overflow` (`hidden` | `scroll` | `auto` | `visible`): CSS overflow behavior
1579
+ - `padding` (`SizeType`): Padding on all sides using theme spacing scale (0-10)
1580
+ - `paddingBottom` (`SizeType`): Bottom padding using theme spacing scale (0-10)
1581
+ - `paddingLeft` (`SizeType`): Left padding using theme spacing scale (0-10)
1582
+ - `paddingRight` (`SizeType`): Right padding using theme spacing scale (0-10)
1583
+ - `paddingTop` (`SizeType`): Top padding using theme spacing scale (0-10)
1584
+ - `paddingX` (`SizeType`): Horizontal padding (left + right) using theme spacing scale (0-10)
1585
+ - `paddingY` (`SizeType`): Vertical padding (top + bottom) using theme spacing scale (0-10)
1586
+ - `position` (`absolute` | `relative` | `static` | `fixed` | `sticky`): CSS position property
1587
+ - `width` (`string`): Width as CSS value (e.g. '100%', '300px')
1588
+
1589
+ ### Carousel (Layout)
1590
+
1591
+ Faixa com rolagem horizontal e setas para passar por cards ou imagens lado a lado.
1592
+ `hideButtonsOnMobile` esconde as setas no celular, onde a rolagem é pelo dedo.
1593
+
1594
+ Nomes antigos que ainda funcionam: Slider.
1595
+
1596
+ Exemplo:
1597
+
1598
+ ```tsx
1599
+ <Carousel sizeToScroll={300}>{cards}</Carousel>
1600
+ ```
1601
+
1602
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/layout-carousel--docs
1603
+
1604
+ Props:
1605
+
1606
+ - `buttonPosition` (`none` | `side` | `bottom`, padrão `bottom`): Position of the navigation buttons - `side` — buttons on left/right sides of the slider - `bottom` — buttons at the bottom center - `none` — no navigation buttons
1607
+ - `children` (`ReactNode`): Content to render inside the scrollable area
1608
+ - `hideButtonsOnMobile` (`boolean`, padrão `false`): Esconde os botões em telas de até 425px, onde a área já rola com o dedo.
1609
+ - `sizeToScroll` (`number`): Number of pixels to scroll on each button click
1610
+
1611
+ ### Divider (Layout)
1612
+
1613
+ Linha fina para separar blocos de conteúdo (seções de um card, itens de um menu, grupos de botões).
1614
+ Use `orientation="vertical"` entre itens lado a lado.
1615
+ Para separar cards inteiros, prefira espaço (`gap`) em vez de linha.
1616
+
1617
+
1618
+ Exemplo:
1619
+
1620
+ ```tsx
1621
+ <Divider spacing="md" />
1622
+ ```
1623
+
1624
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/layout-divider--docs
1625
+
1626
+ Props:
1627
+
1628
+ - `color` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors), padrão `grey_4`): Cor da linha (token).
1629
+ - `orientation` (`horizontal` | `vertical`, padrão `horizontal`): Direção da linha. Na vertical, ocupa a altura do pai (use dentro de um Box em linha).
1630
+ - `spacing` (`SizeType`, padrão `0`): Espaço antes e depois da linha, pela escala do tema (`sm`, `md`, `2`...).
1631
+
1632
+ ### ActionMenu (Navegação)
1633
+
1634
+ Menu de ações de um item (editar, duplicar, excluir), aberto por um botão de três pontos.
1635
+ Setas navegam entre as ações, Enter escolhe, Esc fecha e devolve o foco ao botão.
1636
+ Ação perigosa (`danger`) aparece em vermelho; peça confirmação com ConfirmDialog.
1637
+ Para uma ou duas ações sempre visíveis use IconButton ou Button direto.
1638
+
1639
+
1640
+ Exemplo:
1641
+
1642
+ ```tsx
1643
+ <ActionMenu items={[
1644
+ { label: 'Editar', icon: 'edit2', onClick: editar },
1645
+ { label: 'Excluir', icon: 'delete_bin7', onClick: excluir, danger: true, dividerBefore: true },
1646
+ ]} />
1647
+ ```
1648
+
1649
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/navegação-actionmenu--docs
1650
+
1651
+ Props:
1652
+
1653
+ - `items` (`ActionMenuItem[]`, obrigatória): Ações do menu, de cima para baixo.
1654
+ - `icon` (`IconsName`, valores em lib/ai/icons.txt, padrão `more2`): Ícone do botão que abre o menu.
1655
+ - `label` (`string`, padrão `Mais ações`): Nome do botão que abre o menu, para leitores de tela e ao passar o mouse.
1656
+ - `position` (`top-start` | `top-end` | `bottom-start` | `bottom-end`, padrão `bottom-end`): Lado em que o menu abre.
1657
+ - `variant` (`outlined` | `ghost`, padrão `ghost`): Estilo do botão que abre o menu (variantes do IconButton).
1658
+ - `width` (`string`, padrão `200px`): Largura do menu (valor CSS).
1659
+
1660
+ ### Breadcrumb (Navegação)
1661
+
1662
+ Caminho de navegação do topo da página: ícones dos passos anteriores, seta entre eles e o nome
1663
+ da página atual. Recebe os itens prontos; a navegação fica com quem usa (`href` ou `onClick`).
1664
+
1665
+
1666
+ Exemplo:
1667
+
1668
+ ```tsx
1669
+ <Breadcrumb items={[{ label: 'Dashboard', icon: 'dashboard', href: '/' }, { label: 'Fornecedores', icon: 'group' }]} />
1670
+ ```
1671
+
1672
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/navegação-breadcrumb--docs
1673
+
1674
+ Props:
1675
+
1676
+ - `items` (`BreadcrumbItem[]`, obrigatória): Passos do caminho, do início até a página atual (último).
1677
+ - `showLabels` (`boolean`, padrão `false`): Mostra o nome também nos passos anteriores. Por padrão, como no front, os anteriores mostram só o ícone (e o nome, quando não têm ícone).
1678
+
1679
+ ### Stepper (Navegação)
1680
+
1681
+ Passos numerados de um fluxo longo (cadastro, onboarding, cálculo), ligados pelo gradiente da marca.
1682
+ Passo concluído mostra ✓; o atual fica em destaque. Com `onStepClick`, dá para voltar a passos já feitos.
1683
+ Em telas até 640px vira "Passo X de N" com uma barra de progresso.
1684
+ Para seções que a pessoa visita em qualquer ordem use Tabs.
1685
+
1686
+
1687
+ Exemplo:
1688
+
1689
+ ```tsx
1690
+ <Stepper
1691
+ current={1}
1692
+ steps={[{ id: 'empresa', title: 'Empresa' }, { id: 'docs', title: 'Documentos' }, { id: 'revisao', title: 'Revisão' }]}
1693
+ />
1694
+ ```
1695
+
1696
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/navegação-stepper--docs
1697
+
1698
+ Props:
1699
+
1700
+ - `current` (`number`, obrigatória): Índice do passo atual (começa em 0).
1701
+ - `steps` (`StepperStep[]`, obrigatória): Passos, na ordem.
1702
+ - `compact` (`boolean`): Força a versão compacta ("Passo X de N" + barra). Sem valor, fica compacta em telas até 640px.
1703
+ - `completed` (`number[]`): Índices dos passos já concluídos (mostram ✓). Sem esta prop, os anteriores ao atual contam como concluídos.
1704
+ - `hideLabels` (`boolean`, padrão `false`): Esconde os nomes abaixo das bolinhas.
1705
+ - `labels` (`StepperLabels`): Textos fixos, para tradução.
1706
+ - `onStepClick` (`((index: number) => void)`): Quando presente, deixa voltar para passos anteriores ou concluídos clicando neles.
1707
+
1708
+ ### Tabs (Navegação)
1709
+
1710
+ Abas para alternar entre seções ou visões de um mesmo conteúdo.
1711
+ Aceita textos simples ou itens com ícone, contador e estado desabilitado.
1712
+ Abas em pílula: a ativa ganha borda no gradiente da marca. Com muitas abas, aparecem setas para rolar.
1713
+ Teclado: Tab chega na aba ativa; setas, Home e End trocam de aba.
1714
+ Para trocar só a visualização do mesmo conteúdo (lista × grade) use ViewToggle.
1715
+
1716
+
1717
+ Exemplo:
1718
+
1719
+ ```tsx
1720
+ <Tabs tabs={[{ id: 'ativos', label: 'Ativos', badge: 12 }, { id: 'inativos', label: 'Inativos' }]} active="ativos" onChangeTab={setTab} />
1721
+ ```
1722
+
1723
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/navegação-tabs-tabs--docs
1724
+
1725
+ Props:
1726
+
1727
+ - `tabs` (`(string | TabItem)[]`, obrigatória): Abas: textos simples (v1) ou itens com `id`, `label`, `icon`, `badge` e `disabled`.
1728
+ - `active` (`string`): Aba ativa: o texto (abas simples) ou o `id` (itens).
1729
+ - `color` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): @deprecated Ignorado: a aba ativa usa a borda no gradiente da marca.
1730
+ - `onChangeTab` (`((tab: string, index?: number) => void)`): Chamado ao clicar numa aba. Recebe o texto ou o `id` e a posição.
1731
+ - `variant` (`underline` | `pill`): @deprecated Ignorado: as abas têm um visual só (pílula).
1732
+
1733
+ ### TextLink (Navegação)
1734
+
1735
+ Link em texto, na cor de link do tema, para navegar ou abrir algo.
1736
+ Para ação que muda dados (salvar, excluir) use Button.
1737
+
1738
+
1739
+ Exemplo:
1740
+
1741
+ ```tsx
1742
+ <TextLink href="/ajuda" underline>Saiba mais</TextLink>
1743
+ ```
1744
+
1745
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/navegação-textlink--docs
1746
+
1747
+ Props:
1748
+
1749
+ - `align` (`left` | `right` | `center`): Text alignment
1750
+ - `color` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Text color using theme color tokens
1751
+ - `fontWeight` (`number | "bold" | "normal"`): Font weight — predefined name or numeric value (100-900)
1752
+ - `hoverColor` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Text color on hover using theme color tokens
1753
+ - `hoverUnderline` (`boolean`): Whether to show an underline on hover
1754
+ - `size` (`small` | `2` | `3` | `4` | `5` | `6` | `1` | `medium` | `normal` | `large`): Font size — predefined name or theme typography scale number. - `small`, `normal`, `medium`, `large` — body sizes - `1`-`6` — title sizes (1 = largest, 6 = smallest)
1755
+ - `underline` (`boolean`): Whether to show an underline by default
1756
+
1757
+ ### ViewToggle (Navegação)
1758
+
1759
+ Botões colados para trocar entre poucas visões do mesmo conteúdo (lista × grade, mês × ano).
1760
+ A troca vale na hora. Setas do teclado passam de uma opção para outra.
1761
+ Para seções diferentes de conteúdo use Tabs; para escolha dentro de formulário use RadioGroup.
1762
+
1763
+
1764
+ Exemplo:
1765
+
1766
+ ```tsx
1767
+ <ViewToggle
1768
+ aria-label="Visualização"
1769
+ value={view}
1770
+ onChange={setView}
1771
+ options={[{ value: 'list', label: 'Lista', icon: 'list_unordered' }, { value: 'grid', label: 'Grade', icon: 'layout_grid' }]}
1772
+ />
1773
+ ```
1774
+
1775
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/navegação-tabs-viewtoggle--docs
1776
+
1777
+ Props:
1778
+
1779
+ - `aria-label` (`string`, obrigatória): Nome do grupo para leitores de tela (ex. "Visualização").
1780
+ - `onChange` (`(value: V) => void`, obrigatória): Chamado ao escolher outra opção.
1781
+ - `options` (`ViewToggleOption<V>[]`, obrigatória): Opções, da esquerda para a direita (2 a 5).
1782
+ - `value` (`string`, obrigatória): Valor escolhido.
1783
+ - `fullWidth` (`boolean`, padrão `false`): Ocupa a largura toda, com as opções do mesmo tamanho.
1784
+ - `size` (`sm` | `md`, padrão `md`): Altura: `sm` 32px, `md` 40px.
1785
+
1786
+ ### ConfirmDialog (Sobreposições)
1787
+
1788
+ Pergunta de confirmação antes de uma ação importante (excluir, reprovar, enviar).
1789
+ `variant="danger"` deixa o botão vermelho para ações que apagam ou não têm volta;
1790
+ `reason` pede um motivo antes de confirmar (ex. reprovação).
1791
+ Para confirmar em uma linha de código use o hook `useConfirm` (precisa do `ConfirmDialogProvider`).
1792
+ Para aviso sem decisão use Alert ou Toast.
1793
+
1794
+
1795
+ Exemplo:
1796
+
1797
+ ```tsx
1798
+ <ConfirmDialog
1799
+ open={aberto}
1800
+ title="Excluir fornecedor?"
1801
+ description="Os documentos enviados também serão apagados."
1802
+ variant="danger"
1803
+ confirmLabel="Excluir"
1804
+ onConfirm={excluir}
1805
+ onCancel={() => setAberto(false)}
1806
+ />
1807
+ ```
1808
+
1809
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/sobreposições-confirmdialog--docs
1810
+
1811
+ Props:
1812
+
1813
+ - `onCancel` (`() => void`, obrigatória): Chamado ao cancelar, fechar no X ou apertar Esc.
1814
+ - `onConfirm` (`(reason?: string | undefined) => void`, obrigatória): Chamado ao confirmar; recebe o motivo quando há `reason`.
1815
+ - `open` (`boolean`, obrigatória): Mostra ou esconde a confirmação.
1816
+ - `title` (`string`, obrigatória): Pergunta curta (ex. "Excluir fornecedor?").
1817
+ - `cancelLabel` (`string`, padrão `Cancelar`): Texto do botão de cancelar.
1818
+ - `confirmLabel` (`string`, padrão `Confirmar`): Texto do botão de confirmar.
1819
+ - `description` (`ReactNode`): Explicação do que vai acontecer.
1820
+ - `loading` (`boolean`, padrão `false`): Mostra carregando no botão de confirmar e trava os botões (ex. enquanto salva).
1821
+ - `reason` (`ConfirmDialogReason`): Mostra um campo de motivo antes dos botões.
1822
+ - `variant` (`default` | `danger`, padrão `default`): `danger` pinta o botão de confirmar de vermelho, para ações que apagam ou não têm volta.
1823
+
1824
+ ### Drawer (Sobreposições)
1825
+
1826
+ Painel que desliza da lateral (ou de cima/baixo, com `anchor`) para ver detalhes ou editar sem sair da página.
1827
+ Use quando o conteúdo é longo ou tem rolagem. Para confirmação ou formulário curto use Modal.
1828
+
1829
+
1830
+ Exemplo:
1831
+
1832
+ ```tsx
1833
+ <Drawer isOpen={aberto} setIsOpen={setAberto} anchor="right">...</Drawer>
1834
+ ```
1835
+
1836
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/sobreposições-drawer--docs
1837
+
1838
+ Props:
1839
+
1840
+ - `children` (`ReactNode`, obrigatória): Content rendered inside the drawer
1841
+ - `isOpen` (`boolean`, obrigatória): Whether the drawer is open
1842
+ - `setIsOpen` (`(value: boolean) => void`, obrigatória): Callback to toggle the drawer open/close state
1843
+ - `anchor` (`left` | `right` | `top` | `bottom`, padrão `'bottom'`): Side from which the drawer slides in
1844
+ - `archor` (`left` | `right` | `top` | `bottom`): @deprecated Use `anchor` (nome com erro de digitação, mantido por compatibilidade).
1845
+ - `height` (`string`, padrão `100%`): Height of the drawer as CSS value (used for top/bottom anchors)
1846
+
1847
+ ### Modal (Sobreposições)
1848
+
1849
+ Janela sobre a página para uma decisão curta ou um formulário pequeno (confirmar exclusão, renomear).
1850
+ Fecha com Esc, pelo botão Fechar ou clicando fora. Enquanto aberto, o Tab fica dentro dele e a página não rola;
1851
+ ao fechar, o foco volta para o botão que abriu.
1852
+ Para conteúdo longo ou com rolagem use Drawer.
1853
+
1854
+
1855
+ Exemplo:
1856
+
1857
+ ```tsx
1858
+ <Modal open={aberto} onClose={fechar} title="Excluir fornecedor?">...</Modal>
1859
+ ```
1860
+
1861
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/sobreposições-modal--docs
1862
+
1863
+ Props:
1864
+
1865
+ - `open` (`boolean`, obrigatória): Whether the modal is visible
1866
+ - `children` (`ReactNode`): Content rendered inside the modal body
1867
+ - `customTitle` (`ReactNode`): Custom React element for the title (overrides `title` prop)
1868
+ - `height` (`string`): Height as CSS value
1869
+ - `maxHeight` (`string`): Max height as CSS value
1870
+ - `maxWidth` (`string`): Max width as CSS value
1871
+ - `minHeight` (`string`): Min height as CSS value
1872
+ - `minWidth` (`string`): Min width as CSS value
1873
+ - `onClose` (`((value: boolean) => void)`): Called when the modal is closed (clicking overlay or close button)
1874
+ - `title` (`string`): Title text displayed in the modal header
1875
+ - `width` (`string`): Width as CSS value (e.g. '500px', '80%')
1876
+
1877
+ ### Popover (Sobreposições)
1878
+
1879
+ Caixa flutuante presa a um elemento (`anchorEl`), para menus, filtros e detalhes ao clicar. Fecha ao clicar fora.
1880
+ Para texto curto ao passar o mouse use Tooltip.
1881
+
1882
+
1883
+ Exemplo:
1884
+
1885
+ ```tsx
1886
+ <Popover anchorEl={ancora} onClose={() => setAncora(undefined)}>...</Popover>
1887
+ ```
1888
+
1889
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/sobreposições-popover--docs
1890
+
1891
+ Props:
1892
+
1893
+ - `children` (`ReactNode`, obrigatória): Content rendered inside the popover
1894
+ - `anchorEl` (`HTMLElement`): The HTML element that the popover is anchored to (usually obtained via `useRef`)
1895
+ - `borderRadius` (`string`): Border radius as CSS value (e.g. '8px')
1896
+ - `boxShadow` (`string`): Box shadow as CSS value
1897
+ - `maxHeight` (`string`): Max height as CSS value (enables scroll if content overflows)
1898
+ - `offset` (`number`): Distance in pixels between the popover and the anchor element
1899
+ - `onClose` (`(() => void)`): Called when the popover is closed (clicking outside)
1900
+ - `position` (`left` | `right` | `top` | `bottom` | `auto` | `auto-start` | `auto-end` | `top-start` | `top-end` | `bottom-start` | `bottom-end` | `right-start` | `right-end` | `left-start` | `left-end`, padrão `'bottom'`): Position of the popover relative to the anchor element. Uses Popper.js placement values (e.g. 'top', 'bottom-start', 'right-end')
1901
+ - `width` (`string`): Width as CSS value (e.g. '300px', 'auto')
1902
+
1903
+ ### Text (Texto)
1904
+
1905
+ Texto com tamanho, peso e cor do tema.
1906
+ Em código novo prefira `size` da escala (`bodySm`, `h3`...) e `weight` por nome; os valores da v1 (`size="small"`, `fontWeight={500}`) continuam aceitos.
1907
+
1908
+
1909
+ Exemplo:
1910
+
1911
+ ```tsx
1912
+ <Text size="bodySm" color="grey_2">Atualizado há 2 dias</Text>
1913
+ ```
1914
+
1915
+ Documentação: https://designsystem.blockforce.ai/?path=/docs/texto-text--docs
1916
+
1917
+ Props:
1918
+
1919
+ - `children` (`ReactNode`, obrigatória): Text content or child elements
1920
+ - `align` (`left` | `right` | `center`): Text alignment
1921
+ - `color` (`ThemeColors`, valores em lib/ai/tokens.md (theme.colors)): Text color using theme color tokens (e.g. 'primary', 'grey_3', 'error')
1922
+ - `fontWeight` (`number | "bold" | "normal"`): Font weight — predefined name or numeric value (100-900)
1923
+ - `id` (`string`): Id do elemento, para ligar rótulos e descrições (`aria-labelledby`, `aria-describedby`).
1924
+ - `lineHeight` (`normal` | `tight` | `snug` | `relaxed`): Altura de linha por token: `tight` 1.1, `snug` 1.3, `normal` 1.5, `relaxed` 1.6. Sem ela, o texto usa 1.4 e os títulos 1.1, como sempre.
1925
+ - `size` (`"small" | "2" | "3" | "4" | "5" | "6" | "1" | "h2" | "h3" | "h4" | "medium" | "h1" | "normal" | "large" | (string & Record<never, never>) | "caption" | "bodySm" | "body" | "bodyLg" | "display"`): Font size — predefined name, theme typography scale number, or custom CSS value. - `small`, `normal`, `medium`, `large` — body sizes - `1`-`6` — title sizes (1 = largest, 6 = smallest) - `caption` 12px, `bodySm` 14px, `body` 16px, `bodyLg` 18px, `h4` 22px, `h3` 28px, `h2` 40px, `h1` 56px, `display` 72px — escala da v2 (`theme.typography.textSize`), preferida em código novo - Custom CSS value (e.g. '18px', '1.2rem')
1926
+ - `textTransform` (`none` | `uppercase` | `capitalize` | `lowercase`): Text transform style
1927
+ - `variant` (`small` | `i` | `u` | `p` | `h2` | `h3` | `h4` | `h1` | `h5` | `h6` | `em` | `strong` | `span`, padrão `'p'`): HTML element tag to render (e.g. 'h1', 'p', 'span')
1928
+ - `weight` (`medium` | `light` | `bold` | `regular` | `semibold`): Peso da fonte por token: `light` 300, `regular` 400, `medium` 500, `semibold` 600, `bold` 700. Prefira `weight` a `fontWeight` em código novo. Se as duas vierem, `fontWeight` vence.
1929
+ - `width` (`string`): Width as CSS value (e.g. '100%', '200px')
1930
+
1931
+ ## Hooks e utilitários
1932
+
1933
+ - `getBand`: Faixa em que o valor cai (ex. `getBand(4 * 5, bands)` → faixa "Alto"). Fora de todas as faixas, `undefined`.
1934
+ - `ToastStackStyles`: Estilo das pilhas de toast. O Toast já injeta sozinho; exportado para quem monta pilhas à parte.
1935
+ - `ToastProvider`: Coloca os avisos (toasts) na aplicação para o `useToast` usar. Envolva o app uma vez, perto do ThemeProvider. Os avisos empilham no canto escolhido (`position`) e somem sozinhos depois de `duration`. Para um aviso controlado por estado numa tela só, use o Toast direto.
1936
+ - `useToast`: Abre avisos de qualquer lugar do app: `toast.success('Fornecedor salvo')`. Precisa do `ToastProvider` acima na árvore.
1937
+ - `ConfirmDialogProvider`: Coloca um ConfirmDialog na aplicação para o `useConfirm` usar. Envolva o app uma vez, perto do ThemeProvider.
1938
+ - `useConfirm`: Abre a confirmação e espera a resposta: `true` se confirmou, `false` se cancelou. Precisa do `ConfirmDialogProvider` acima na árvore.
1939
+ - `formatDateKey`: `AAAA-MM-DD` → texto no formato do idioma (ex. `21/10/2026`). Vazio fica vazio.
1940
+ - `parseDateText`: Texto digitado (ex. `21/10/2026`) → `AAAA-MM-DD`, ou `undefined` se não for uma data que existe.
1941
+ - `initialDay`: Dia inicial do calendário: o valor, ou hoje puxado para dentro dos limites.
1942
+ - `LUCIDE_PREFIX`: Prefixo dos ícones da Lucide no `name` (ex. `lu:leaf`). Nomes sem prefixo continuam sendo da Remix.
1943
+ - `isLucideName`: `true` quando o nome é de um ícone da Lucide (`lu:...`).
1944
+ - `parseIconNameToLucide`: Converte `lu:file_text` (ou `lu:file-text`) para o componente `LuFileText`.
1945
+ - `useMediaQuery`: Diz se uma media query casa com a tela atual e acompanha mudanças. Lê a tela já no primeiro render. Em Next, passe `{ ssr: true }`: o primeiro render devolve `false` (igual ao servidor) e logo depois de montar passa a refletir a tela.
1946
+ - `useIsMobile`: `true` em celular: largura até `md` (768px), inclusive.
1947
+ - `useIsTablet`: `true` em tablet: largura acima de `md` (768px) e até `lg` (1024px).
1948
+ - `useBreakpoint`: Faixa de largura atual: `base` (até 480px), `xs` (acima de 480), `sm` (acima de 640), `md` (acima de 768), `lg` (acima de 1024) ou `xl` (acima de 1280). No servidor devolve `xl`. Lê a tela já no primeiro render. Em Next, passe `{ ssr: true }`: o primeiro render devolve `xl` (igual ao servidor) e logo depois de montar reflete a tela.
1949
+ - `CHART_COLOR_ORDER`: Ordem das cores das séries: degradê a partir do roxo da marca (roxo → azuis → teal → quentes).
1950
+ - `CHART_OTHER_COLOR`: Cor reservada para a fatia "outros", fora do ciclo das séries.
1951
+ - `getChartColors`: As 7 cores das séries, em ordem de degradê. O cinza de "outros" fica de fora (`theme.colors.chart.grey`). Com mais de 7 séries, agrupe o resto em "outros"; se não der, a lista recomeça.
1952
+ - `SUPPORTED_CLIENT_FONTS`: Fontes que um tema de cliente pode usar. Qualquer outra volta para a fonte Blockforce.
1953
+ - `getClientThemeIssues`: Confere a marca do cliente sem montar o tema. - As cores precisam estar em hex com `#` (`#1D428A` ou `#14A`), sem transparência. - `primary` precisa de contraste 4.5:1 com texto branco (é fundo de botão). - `accent` precisa de contraste 3:1 com o fundo do card (é detalhe gráfico). - `fontFamily` precisa estar na lista suportada.
1954
+ - `createClientTheme`: Monta o tema com a marca de um cliente sobre a base Blockforce. Estrutura, espaços, estados e acessibilidade continuam os da Blockforce; só cor principal, cor de destaque e fonte mudam. Valor com problema (ver `getClientThemeIssues`) é ignorado e o padrão Blockforce fica no lugar. O gradiente só usa as cores do cliente quando as duas passam; com uma só, fica o gradiente Blockforce, para não misturar as marcas. A paleta de gráfico (`colors.chart`) não muda. Sem opções, devolve o tema Blockforce.
1955
+ - `defaultTheme`: Tema padrão Blockforce. Montado a partir dos tokens; para mudar um valor, edite `tokens/*.tokens.json`.
1956
+ - `breakpointValues`: Larguras de tela em pixels, como número.
1957
+ - `media`: Media queries prontas para usar dentro de styled-components. A largura do breakpoint pertence ao lado de baixo: `down('md')` inclui 768px, `up('md')` começa em 769px.
1958
+ - `getThemeColor`: Resolve um nome de cor do tema para o valor CSS. Aceita nomes (`primary`, `success`, `grey_3`), caminhos com ponto (`brand.gradient`, `stateSubtle.error`) e, se não achar no tema, devolve o valor como veio (ex. `transparent`).
1959
+ - `getThemeSize`: Resolve um tamanho de texto: `textSize` (`body`, `bodySm`, `h3`…), `body_size` e `title_size` da v1, ou o valor CSS como veio.
1960
+ - `getThemeSpacing`: Resolve um espaçamento: número da escala (`2` = 16px), nome (`md` = 16px) ou valor CSS (`10px`). `0` devolve `undefined` de propósito: o Box usa 0 como "não definido" para não sobrescrever o `padding` geral.
1961
+ - `adjustColorBrightness`: Adjusts the brightness of a given color by a specified factor.
1962
+ - `getLuminance`: Luminância relativa (WCAG 2.1) de uma cor hex.
1963
+ - `getContrastRatio`: Razão de contraste (WCAG 2.1) entre duas cores hex, de 1 a 21. Texto normal precisa de 4.5, texto grande e ícones de 3. Devolve `undefined` se alguma cor não for hex.
1964
+ - `mixColors`: Mistura duas cores hex. `weight` é quanto da primeira entra (0 a 1). Devolve `undefined` se alguma não for hex.
1965
+ - `getReadableTextColor`: Cor de texto legível a partir de uma cor do tema: devolve a própria cor quando ela já tem contraste com o fundo; senão, escurece aos poucos até chegar lá. Use quando o texto leva a cor de uma categoria (ex. título de seção em `chart.blue`). Cores que não são hex voltam como estão.
1966
+
1967
+ ## Tokens
1968
+
1969
+ Gerado de `src/theme` e `tokens/*.tokens.json`. Use sempre o token, nunca o valor solto.
1970
+
1971
+ ## No React (`theme`)
1972
+
1973
+ | Token | Valor | Descrição |
1974
+ |---|---|---|
1975
+ | `theme.colors.primary` | `#6633CC` | Roxo da marca Blockforce. |
1976
+ | `theme.colors.secondary` | `#00CC99` | Teal da marca Blockforce. |
1977
+ | `theme.colors.brand.gradient` | `linear-gradient(45deg, #6633CC 0%, #00CC99 100%)` | Gradiente da marca: o único, sempre no ângulo da logo (45°, roxo embaixo à esquerda, teal em cima à direita). Todo componente com gradiente usa este token; não criar outro ângulo nem outras cores. |
1978
+ | `theme.colors.border.focus` | `#6633CC` | Roxo de foco, para foco de marca em peças novas e no tema do cliente. Campos usam a própria cor de borda no foco. |
1979
+ | `theme.colors.white` | `#FFFFFF` | Branco. |
1980
+ | `theme.colors.interactive` | `#1779B2` | Links e ações textuais. |
1981
+ | `theme.colors.state.success` | `#27AE60` | Sucesso, aprovado, concluído. Ícones, bordas e preenchimentos. |
1982
+ | `theme.colors.state.warning` | `#F79009` | Alerta, pendente, atenção. Ícones, bordas e preenchimentos. |
1983
+ | `theme.colors.state.error` | `#EB5757` | Erro, reprovado, ação destrutiva. |
1984
+ | `theme.colors.state.info` | `#2F80ED` | Informação neutra. |
1985
+ | `theme.colors.stateSubtle.success` | `#ECFDF3` | Fundo de etiqueta ou aviso de sucesso. |
1986
+ | `theme.colors.stateSubtle.warning` | `#FEF3E7` | Fundo de etiqueta ou aviso de alerta. |
1987
+ | `theme.colors.stateSubtle.error` | `#FDECEA` | Fundo de etiqueta ou aviso de erro. |
1988
+ | `theme.colors.stateSubtle.info` | `#E8F3FA` | Fundo de etiqueta ou aviso de informação. |
1989
+ | `theme.colors.stateText.success` | `#067647` | Texto de sucesso sobre fundo claro (contraste AA). |
1990
+ | `theme.colors.stateText.warning` | `#DC6803` | Texto de alerta. Contraste 3.5:1 no branco, abaixo do AA para texto pequeno: use em semibold ou maior, sempre junto de ícone. Tom escolhido para não parecer vermelho. |
1991
+ | `theme.colors.stateText.error` | `#C0392B` | Texto de erro sobre fundo claro (contraste AA). |
1992
+ | `theme.colors.stateText.info` | `#0F5E8C` | Texto de informação sobre fundo claro (contraste AA). |
1993
+ | `theme.colors.chart.purple` | `#6633CC` | Roxo da marca. |
1994
+ | `theme.colors.chart.lilac` | `#B692F6` | Lilás. |
1995
+ | `theme.colors.chart.lightBlue` | `#ABD0FD` | Azul clarinho, pastel. |
1996
+ | `theme.colors.chart.blue` | `#36BFFA` | Azul ciano. |
1997
+ | `theme.colors.chart.teal` | `#00CC99` | Teal da marca. |
1998
+ | `theme.colors.chart.orange` | `#FAC074` | Laranja pastel. |
1999
+ | `theme.colors.chart.pink` | `#F670C7` | Rosa. |
2000
+ | `theme.colors.chart.grey` | `#D9D9D9` | Cinza, para "outros" ou o que sobra. |
2001
+ | `theme.colors.grey_1` | `#333333` | Cinza 1, o mais escuro. Texto principal. |
2002
+ | `theme.colors.grey_2` | `#666666` | Cinza 2. Texto de apoio. |
2003
+ | `theme.colors.grey_3` | `#7D7D7D` | Cinza 3. Rótulos e textos auxiliares. |
2004
+ | `theme.colors.grey_4` | `#D9D9D9` | Cinza 4. Bordas. |
2005
+ | `theme.colors.grey_5` | `#F3F3F3` | Cinza 5. Fundo de áreas de apoio. |
2006
+ | `theme.colors.grey_6` | `#F8F7FC` | Cinza 6, o mais claro, com um toque do roxo da marca. Fundo de página e destaque leve (hover de linha). |
2007
+ | `theme.typography.fontFamily` | `Inter, system-ui, -apple-system, 'Segoe UI', sans-serif` | Fonte da marca. O projeto que consome carrega o Inter (300 a 700). A v1 usava Rubik (legacyTheme). |
2008
+ | `theme.typography.monoFamily` | `'JetBrains Mono', ui-monospace, SFMono-Regular, monospace` | Fonte monoespaçada para código e números tabulares. |
2009
+ | `theme.typography.fontWeight.light` | `300` | Leve. Uso raro, textos grandes. |
2010
+ | `theme.typography.fontWeight.regular` | `400` | Texto corrido. |
2011
+ | `theme.typography.fontWeight.medium` | `500` | Rótulos e destaques leves. |
2012
+ | `theme.typography.fontWeight.semibold` | `600` | Títulos de seção e cabeçalhos. |
2013
+ | `theme.typography.fontWeight.bold` | `700` | Títulos principais e números de destaque. |
2014
+ | `theme.typography.lineHeight.tight` | `1.1` | Títulos grandes. |
2015
+ | `theme.typography.lineHeight.snug` | `1.3` | Títulos médios. |
2016
+ | `theme.typography.lineHeight.normal` | `1.5` | Texto corrido compacto. |
2017
+ | `theme.typography.lineHeight.relaxed` | `1.6` | Texto corrido longo. |
2018
+ | `theme.typography.textSize.caption` | `12px` | Legendas e textos auxiliares. Menor tamanho permitido. |
2019
+ | `theme.typography.textSize.bodySm` | `14px` | Texto corrido compacto (tabelas, formulários). |
2020
+ | `theme.typography.textSize.body` | `16px` | Texto corrido padrão. |
2021
+ | `theme.typography.textSize.bodyLg` | `18px` | Texto corrido de destaque. |
2022
+ | `theme.typography.textSize.h4` | `22px` | Título de card ou bloco. |
2023
+ | `theme.typography.textSize.h3` | `28px` | Título de seção. |
2024
+ | `theme.typography.textSize.h2` | `40px` | Título de página. |
2025
+ | `theme.typography.textSize.h1` | `56px` | Título principal. |
2026
+ | `theme.typography.textSize.display` | `72px` | Título de capa e hero. |
2027
+ | `theme.spacing.1` | `8px` | 8px, unidade da grade. |
2028
+ | `theme.spacing.2` | `16px` | 16px. |
2029
+ | `theme.spacing.3` | `24px` | 24px. |
2030
+ | `theme.spacing.4` | `32px` | 32px. |
2031
+ | `theme.spacing.5` | `40px` | 40px. |
2032
+ | `theme.spacing.6` | `56px` | 56px. |
2033
+ | `theme.spacing.7` | `72px` | 72px. |
2034
+ | `theme.spacing.8` | `80px` | 80px. |
2035
+ | `theme.spacing.9` | `96px` | 96px. |
2036
+ | `theme.spacing.10` | `120px` | 120px. |
2037
+ | `theme.spacing.0.5` | `4px` | 4px. |
2038
+ | `theme.spacing.1.5` | `12px` | 12px. |
2039
+ | `theme.spacing.xs` | `4px` | 4px. |
2040
+ | `theme.spacing.sm` | `8px` | 8px, unidade da grade. |
2041
+ | `theme.spacing.md` | `16px` | 16px. |
2042
+ | `theme.spacing.lg` | `24px` | 24px. |
2043
+ | `theme.spacing.xl` | `32px` | 32px. |
2044
+ | `theme.spacing.2xl` | `48px` | 48px. |
2045
+ | `theme.radius.none` | `0px` | Sem arredondamento. |
2046
+ | `theme.radius.sm` | `4px` | Checkbox, etiquetas pequenas. |
2047
+ | `theme.radius.md` | `8px` | Botões e campos. |
2048
+ | `theme.radius.lg` | `12px` | Cards. |
2049
+ | `theme.radius.xl` | `16px` | Tabelas, painéis e modais. |
2050
+ | `theme.radius.2xl` | `24px` | Blocos grandes de destaque. |
2051
+ | `theme.radius.full` | `9999px` | Pílula e círculo. |
2052
+ | `theme.shadow.xs` | `0px 1px 2px 0px #0000000D` | Campos e botões. |
2053
+ | `theme.shadow.sm` | `0px 2px 8px 0px #0000000F` | Cards em repouso. |
2054
+ | `theme.shadow.md` | `0px 4px 16px 0px #00000014` | Cards em destaque e hover. |
2055
+ | `theme.shadow.lg` | `0px 8px 32px 0px #0000001A` | Modais, menus e dropdowns. |
2056
+ | `theme.shadow.xl` | `0px 16px 48px 0px #0000001F` | Elementos flutuantes de destaque. |
2057
+ | `theme.shadow.focus` | `0px 0px 0px 4px #6633CC3D` | Anel de foco roxo (24%), para foco de marca em peças novas. Campos e botões usam o anel cinza que acompanha a borda. |
2058
+ | `theme.shadow.button` | `0px 2px 8px 0px #0000000F` | |
2059
+ | `theme.breakpoints.xs` | `480px` | Celular grande. |
2060
+ | `theme.breakpoints.sm` | `640px` | Celular deitado. |
2061
+ | `theme.breakpoints.md` | `768px` | Tablet. Abaixo disso é celular. |
2062
+ | `theme.breakpoints.lg` | `1024px` | Notebook pequeno. |
2063
+ | `theme.breakpoints.xl` | `1280px` | Desktop. |
2064
+ | `theme.zIndex.drawer` | `1100` | Painéis laterais (Drawer). |
2065
+ | `theme.zIndex.modal` | `1200` | Modais. Ficam acima do Drawer. |
2066
+ | `theme.zIndex.dropdown` | `1300` | Select, popover e menus. Abrem soltos na página, então ficam acima do Modal para funcionar dentro dele. |
2067
+ | `theme.zIndex.toast` | `1400` | Avisos no canto da tela. |
2068
+ | `theme.zIndex.tooltip` | `1500` | Tooltips, sempre por cima. |
2069
+ | `theme.motion.duration.fast` | `120ms` | Mudança de estado pequena (hover de cor). |
2070
+ | `theme.motion.duration.normal` | `200ms` | Transição padrão. |
2071
+ | `theme.motion.duration.slow` | `300ms` | Abertura de painel e revelação de card. |
2072
+ | `theme.motion.easing.default` | `cubic-bezier(0.4, 0, 0.2, 1)` | Entra e sai suave (ease-in-out). |
2073
+ | `theme.motion.easing.enter` | `cubic-bezier(0, 0, 0.2, 1)` | Elemento entrando (ease-out). |
2074
+ | `theme.motion.easing.exit` | `cubic-bezier(0.4, 0, 1, 1)` | Elemento saindo (ease-in). |
2075
+
2076
+ Chaves da v1 (`colors.custom`, `box_shadow`, `border_radius`, `title_size`, `body_size`, `typography.family`) continuam aceitas como apelido, mas não use em código novo. A troca está no `MIGRATION.md`.
2077
+
2078
+ ## Fora do React (`lib/tokens/tokens.css`)
2079
+
2080
+ Para HTML, slides, landing e vídeo: importe `blockforce-design-system/lib/tokens/tokens.css` e use as variáveis.
2081
+
2082
+ ```css
2083
+ --bf-color-purple-500: #6633CC
2084
+ --bf-color-teal-500: #00CC99
2085
+ --bf-color-navy-900: #1A202B
2086
+ --bf-color-white: #FFFFFF
2087
+ --bf-color-grey-1: #333333
2088
+ --bf-color-grey-2: #666666
2089
+ --bf-color-grey-3: #7D7D7D
2090
+ --bf-color-grey-4: #D9D9D9
2091
+ --bf-color-grey-5: #F3F3F3
2092
+ --bf-color-grey-6: #F8F7FC
2093
+ --bf-color-green-50: #ECFDF3
2094
+ --bf-color-green-500: #27AE60
2095
+ --bf-color-green-700: #067647
2096
+ --bf-color-orange-50: #FEF3E7
2097
+ --bf-color-orange-200: #FAC074
2098
+ --bf-color-orange-500: #F79009
2099
+ --bf-color-orange-700: #DC6803
2100
+ --bf-color-red-50: #FDECEA
2101
+ --bf-color-red-500: #EB5757
2102
+ --bf-color-red-700: #C0392B
2103
+ --bf-color-blue-50: #E8F3FA
2104
+ --bf-color-blue-200: #ABD0FD
2105
+ --bf-color-blue-500: #2F80ED
2106
+ --bf-color-blue-600: #1779B2
2107
+ --bf-color-blue-700: #0F5E8C
2108
+ --bf-color-lilac-300: #B692F6
2109
+ --bf-color-pink-400: #F670C7
2110
+ --bf-color-cyan-400: #36BFFA
2111
+ --bf-font-family-sans: Inter, system-ui, -apple-system, 'Segoe UI', sans-serif
2112
+ --bf-font-family-mono: 'JetBrains Mono', ui-monospace, SFMono-Regular, monospace
2113
+ --bf-font-weight-light: 300
2114
+ --bf-font-weight-regular: 400
2115
+ --bf-font-weight-medium: 500
2116
+ --bf-font-weight-semibold: 600
2117
+ --bf-font-weight-bold: 700
2118
+ --bf-font-size-caption: 12px
2119
+ --bf-font-size-body-sm: 14px
2120
+ --bf-font-size-body: 16px
2121
+ --bf-font-size-body-lg: 18px
2122
+ --bf-font-size-h4: 22px
2123
+ --bf-font-size-h3: 28px
2124
+ --bf-font-size-h2: 40px
2125
+ --bf-font-size-h1: 56px
2126
+ --bf-font-size-display: 72px
2127
+ --bf-font-line-height-tight: 1.1
2128
+ --bf-font-line-height-snug: 1.3
2129
+ --bf-font-line-height-normal: 1.5
2130
+ --bf-font-line-height-relaxed: 1.6
2131
+ --bf-space-0: 0px
2132
+ --bf-space-4: 4px
2133
+ --bf-space-8: 8px
2134
+ --bf-space-12: 12px
2135
+ --bf-space-16: 16px
2136
+ --bf-space-24: 24px
2137
+ --bf-space-32: 32px
2138
+ --bf-space-40: 40px
2139
+ --bf-space-48: 48px
2140
+ --bf-space-56: 56px
2141
+ --bf-space-72: 72px
2142
+ --bf-space-80: 80px
2143
+ --bf-space-96: 96px
2144
+ --bf-space-120: 120px
2145
+ --bf-radius-none: 0px
2146
+ --bf-radius-sm: 4px
2147
+ --bf-radius-md: 8px
2148
+ --bf-radius-lg: 12px
2149
+ --bf-radius-xl: 16px
2150
+ --bf-radius-2xl: 24px
2151
+ --bf-radius-full: 9999px
2152
+ --bf-shadow-xs: 0px 1px 2px 0px #0000000D
2153
+ --bf-shadow-sm: 0px 2px 8px 0px #0000000F
2154
+ --bf-shadow-md: 0px 4px 16px 0px #00000014
2155
+ --bf-shadow-lg: 0px 8px 32px 0px #0000001A
2156
+ --bf-shadow-xl: 0px 16px 48px 0px #0000001F
2157
+ --bf-shadow-focus: 0px 0px 0px 4px #6633CC3D
2158
+ --bf-breakpoint-xs: 480px
2159
+ --bf-breakpoint-sm: 640px
2160
+ --bf-breakpoint-md: 768px
2161
+ --bf-breakpoint-lg: 1024px
2162
+ --bf-breakpoint-xl: 1280px
2163
+ --bf-z-index-drawer: 1100
2164
+ --bf-z-index-modal: 1200
2165
+ --bf-z-index-dropdown: 1300
2166
+ --bf-z-index-toast: 1400
2167
+ --bf-z-index-tooltip: 1500
2168
+ --bf-duration-fast: 120ms
2169
+ --bf-duration-normal: 200ms
2170
+ --bf-duration-slow: 300ms
2171
+ --bf-easing-default: cubic-bezier(0.4, 0, 0.2, 1)
2172
+ --bf-easing-enter: cubic-bezier(0, 0, 0.2, 1)
2173
+ --bf-easing-exit: cubic-bezier(0.4, 0, 1, 1)
2174
+ --bf-brand-gradient: linear-gradient(45deg, #6633CC 0%, #00CC99 100%)
2175
+ --bf-border-focus: #6633CC
2176
+ --bf-interactive: #1779B2
2177
+ --bf-state-success: #27AE60
2178
+ --bf-state-warning: #F79009
2179
+ --bf-state-error: #EB5757
2180
+ --bf-state-info: #2F80ED
2181
+ --bf-state-subtle-success: #ECFDF3
2182
+ --bf-state-subtle-warning: #FEF3E7
2183
+ --bf-state-subtle-error: #FDECEA
2184
+ --bf-state-subtle-info: #E8F3FA
2185
+ --bf-state-text-success: #067647
2186
+ --bf-state-text-warning: #DC6803
2187
+ --bf-state-text-error: #C0392B
2188
+ --bf-state-text-info: #0F5E8C
2189
+ --bf-chart-purple: #6633CC
2190
+ --bf-chart-lilac: #B692F6
2191
+ --bf-chart-light-blue: #ABD0FD
2192
+ --bf-chart-blue: #36BFFA
2193
+ --bf-chart-teal: #00CC99
2194
+ --bf-chart-orange: #FAC074
2195
+ --bf-chart-pink: #F670C7
2196
+ --bf-chart-grey: #D9D9D9
2197
+ ```