# 1DS — Design System da 1Doc (React) — documentação completa Pacote `@1doc/1ds-react` v2.5.0. Gerado de https://1ds.1doc.com.br/react/latest/llms.txt. Contém 70 páginas: 61 componentes, 3 foundations e 6 guidelines. --- # Accordion > Accordion component — lista de painéis expansíveis (sanfona). - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { Accordion } from '@1doc/1ds-react';` ## Quando usar Conteúdo que fica RECOLHIDO até o usuário querer: FAQ, seções opcionais de formulário, detalhes secundários. Vários podem abrir juntos com `multiple`. ## Quando NÃO usar Para alternar entre visões equivalentes sempre disponíveis — use `Tabs`. Se o conteúdo é essencial, não esconda atrás de acordeão. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `items` | `AccordionItemData[]` | Itens do accordion (id, title, content, disabled?, defaultOpen?) | | `multiple` | `boolean` | Permite manter vários painéis abertos ao mesmo tempo | | `variant` | `"default" \| "bordered" \| "separated"` | Estilo visual: 'default' \| 'bordered' \| 'separated' | | `className` | `string` | Classes CSS adicionais | ## Tipos auxiliares Exportados pelo mesmo pacote e necessários para montar as props de coleção. ```ts export interface AccordionItemData { id: string; title: string; /** Conteúdo do painel — aceita ReactNode no React (no Vue, prefira string) */ content: any; disabled?: boolean; defaultOpen?: boolean; } ``` ## Exemplo ```tsx import { Accordion } from '@1doc/1ds-react'; ``` --- # AIContent > AIContent — envolve conteúdo gerado por IA, marca visualmente enquanto ele é da IA, e tira a marca quando o usuário edita. PREVIEW: a API pode mudar sem aviso. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { AIContent } from '@1doc/1ds-react';` ## Quando usar Envolver um trecho GERADO que o usuário pode editar: rascunho de despacho, resumo, sugestão de texto. É o componente que garante que a edição do usuário vence e continua reversível. ## Quando NÃO usar Para conteúdo gerado que o usuário NÃO edita — aí basta `AILabel` no cabeçalho do bloco. Para conteúdo que nunca foi da IA, não use nenhum dos dois. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `edited` | `any` | Conteúdo já foi editado pelo usuário. Controlado pelo host: só ele sabe se o texto mudou. Com `true`, o tratamento de IA sai e aparece a ação de reverter. | | `onRevert` | `(event?: any) => void` | Volta para a versão da IA. Sem isto, não há reverter e a edição é caminho sem volta. | | `revertLabel` | `string` | Rótulo da ação de reverter (padrão: "Reverter para a sugestão da IA") | | `editedLabel` | `string` | Texto que marca o conteúdo como editado (padrão: "Editado por você") | | `locked` | `any` | Conteúdo confirmado (assinado, despachado). Trava o reverter: depois do ato oficial não se "desfaz", emite-se outro. | | `lockedLabel` | `string` | Texto exibido quando travado (padrão: "Confirmado — não é mais reversível") | | `explanation` | `any` | Explicação repassada ao AILabel interno | | `sources` | `string[]` | Fontes repassadas ao AILabel interno | | `notIncluded` | `string` | O que não entrou, repassado ao AILabel interno | | `hideLabel` | `any` | Não renderiza o selo interno. Use quando já existe um AILabel no cabeçalho do bloco — a guideline pede um selo por bloco, não um por parágrafo. | | `className` | `string` | Classes CSS adicionais | | `id` | `string` | Id do elemento raiz | | `children` | `any` | — | ## Exemplo ```tsx import { AIContent } from '@1doc/1ds-react'; Exemplo AIContent ``` --- # AILabel > AILabel — selo que marca conteúdo gerado por IA, com painel de explicabilidade. PREVIEW: a API pode mudar sem aviso. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { AILabel } from '@1doc/1ds-react';` ## Quando usar Marcar conteúdo GERADO por um modelo: resumo, sugestão de texto, classificação inferida, resposta de assistente. Um selo por bloco, no começo do bloco. ## Quando NÃO usar Para o que sempre foi automático e ninguém chamava de IA — busca, ordenação, autocompletar, validação de formato, cálculo. Marcar isso dilui o selo até ele virar decoração. Para status ou categoria, use `Tag`; para contagem, use `Badge`. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `label` | `string` | Texto do selo (padrão: "IA") | | `size` | `"sm" \| "md"` | Tamanho do selo: 'sm' \| 'md' | | `explanation` | `any` | Explicação de COMO o conteúdo foi gerado. Sem ela o selo é só rótulo, e o painel não abre. | | `explanationTitle` | `string` | Título do painel (padrão: "Como isto foi gerado") | | `sources` | `string[]` | De ONDE veio: documentos, campos ou histórico que alimentaram a saída | | `notIncluded` | `string` | O que NÃO entrou na geração (recorte de período, tipo de documento ignorado). É a parte que o usuário não tem como adivinhar. | | `fixLabel` | `string` | Rótulo da ação de correção (padrão: "Corrigir manualmente") | | `onFix` | `(event?: any) => void` | Ação para quando a saída estiver errada. Sem caminho de correção, a explicabilidade informa e não resolve. | | `open` | `any` | Painel aberto (modo controlado) | | `defaultOpen` | `boolean` | Painel aberto inicialmente (modo não-controlado) | | `onOpenChange` | `(open: boolean) => void` | Callback ao abrir ou fechar o painel (recebe boolean) | | `className` | `string` | Classes CSS adicionais | | `id` | `string` | Id do elemento raiz | | `ariaLabel` | `string` | Descrição acessível do selo. Padrão: "Conteúdo gerado por IA". | | `children` | `any` | — | ## Exemplo ```tsx import { AILabel } from '@1doc/1ds-react'; Exemplo AILabel ``` --- # Alert > Componente Alert é utilizado para comunicar mensagens importantes que requerem a atenção imediata do usuário. Pode indicar sucessos, avisos, erros ou informações relevantes de forma clara e destacada. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { Alert } from '@1doc/1ds-react';` ## Quando usar Mensagem PERSISTENTE ancorada na página, que permanece enquanto a condição existir: erro de validação do formulário, aviso de manutenção, resultado de uma operação que o usuário precisa reler. ## Quando NÃO usar Para retorno TRANSITÓRIO de uma ação que o usuário acabou de fazer ("Salvo com sucesso") — use `Toast`. Para exigir decisão, use `ConfirmDialog`. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `dismissLabel` | `string` | Rótulo acessível do botão de dispensar. @default 'Dispensar alerta' | | `title` | `string` | Título do alerta. | | `description` | `string` | Propriedade obrigatória do aviso que explica do que se trata o alerta. | | `variant` | `"neutral" \| "positive" \| "info" \| "negative"` | Variante semântica (cor/finalidade) do alerta. | | `appearance` | `"soft" \| "solid"` | Estilo visual ('soft' para fundos claros; 'solid' para preenchimentos escuros/cores fortes). | | `verticalPosition` | `"top" \| "bottom"` | Posição vertical na tela para a exibição flutuante. Quando nenhuma posição é informada, o alerta é renderizado inline (no fluxo). | | `horizontalPosition` | `"left" \| "center" \| "right"` | Posição horizontal na tela para a exibição flutuante. Quando nenhuma posição é informada, o alerta é renderizado inline (no fluxo). | | `time` | `number` | Tempo em milissegundos que o alerta ficará na tela e desaparecerá. Se 0, ou não definido, o alerta não desaparece de forma automática. | | `dismissable` | `boolean` | Define ou não a visibilidade do ícone de dispensar o aviso. | | `content` | `any` | Possibilita uso de elementos HTML/Componentes JSX ou text simples no bloco de ação (links/etc). | | `children` | `any` | Slot principal no Mitosis para o custom content generalizado. | | `className` | `string` | Permite sobrescrever classes customizadas na raiz do container do alerta | | `id` | `string` | Id aplicado ao container raiz do alerta. | | `onClose` | `(event?: any) => void` | Evento acionado ao clicar para fechar o alerta | ## Exemplo ```tsx import { Alert } from '@1doc/1ds-react'; Exemplo Alert ``` --- # AppHeader > Barra superior da aplicação. Extraído do cabeçalho real da 1Doc (`components/layout/Header.tsx` do protótipo), não desenhado do zero: a anatomia, a ordem das regiões e as medidas são as de lá. O que o produto decide é o CONTEÚDO — quais itens de navegação, quais ações, qual menu do usuário. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { AppHeader } from '@1doc/1ds-react';` ## Quando usar Como topo fixo de uma aplicação: marca, ação principal, navegação, busca, ações e usuário. ## Quando NÃO usar Para o cabeçalho de uma PÁGINA (título e ações do registro aberto) — use `PageHeader`. Para a faixa de contexto abaixo desta barra, use `AppSubheader`. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `primaryActionLabel` | `string` | Rótulo da ação principal, à esquerda da navegação (na 1Doc, "Novo"). Sem ele o botão não aparece. | | `primaryActionIcon` | `IconProp` | Ícone da ação principal. | | `onPrimaryAction` | `() => void` | Acionado no clique da ação principal. | | `searchPlaceholder` | `string` | Texto de apoio do campo de busca. Sem ele o campo não aparece. | | `searchValue` | `string` | Valor do campo de busca (controlado). | | `onSearchChange` | `(valor: string) => void` | Acionado a cada tecla no campo de busca. | | `userName` | `string` | Nome exibido ao lado do avatar. Sem ele o bloco do usuário não aparece. | | `userInitials` | `string` | Iniciais dentro do avatar (ex.: "CL"). | | `onUserClick` | `() => void` | Acionado no clique do bloco do usuário. | | `bordered` | `boolean` | Linha inferior de separação. @default true | | `className` | `string` | Classes CSS adicionais. | | `brand` | `any` | Marca. O padrão é o `Logo` da 1Doc; passe outro conteúdo para substituir. | | `children` | `any` | Navegação principal — normalmente uma lista de `AppNavItem`. | | `search` | `any` | Campo de busca próprio, no lugar do padrão. | | `actions` | `any` | Ícones de ação: tema, idioma, notificações. Recebem espaçamento e cor da barra. | | `assistant` | `any` | Gatilho do assistente, entre as ações e o usuário. | | `userMenu` | `any` | Menu do usuário, renderizado ancorado ao bloco do usuário. | ## Exemplo ```tsx import { AppHeader } from '@1doc/1ds-react'; Exemplo AppHeader ``` --- # AppHeaderAction > Botão de ação do cabeçalho: um ícone, opcionalmente com contador. Extraído de `.onb-header__action-btn` + `.ntf-badge` do protótipo da 1Doc — o sino com o número de não lidas, o seletor de idioma, o alternador de tema. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { AppHeaderAction } from '@1doc/1ds-react';` ## Quando usar Ações de ícone na ponta direita do `AppHeader`. ## Quando NÃO usar Para um item de navegação com rótulo — use `AppNavItem`. Para um botão comum de formulário ou de página — use `Button`. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `icon` | `IconProp` | Ícone da ação. Use a família `regular` — é a do cabeçalho da 1Doc. | | `label` | `string` | Nome acessível, e também a dica ao passar o mouse. Obrigatório na prática: o botão não tem texto. | | `badge` | `string \| number` | Contador sobreposto ao ícone. `0` ou vazio não desenha nada — "tem algo" sem número não ajuda a decidir se vale abrir. | | `badgeLabel` | `string` | O que o contador significa (ex.: "não lidas"). Entra no nome acessível. | | `active` | `boolean` | Marca a ação como a do painel aberto no momento. | | `onClick` | `() => void` | Acionado no clique. | | `className` | `string` | Classes CSS adicionais. | | `children` | `any` | Conteúdo ancorado ao botão — normalmente o painel que ele abre. | ## Exemplo ```tsx import { AppHeaderAction } from '@1doc/1ds-react'; Exemplo AppHeaderAction ``` --- # AppNavItem > AppNavItem — um item da navegação horizontal do `AppHeader`. É o `Inbox ▾`, o `Tarefas 9`, o `Fila de assinaturas 14` do topo da 1Doc: rótulo, contador opcional e seta quando abre um menu. Existe como componente próprio porque essa combinação era remontada em cada produto, e o contador é justamente o pedaço que costuma sair sem nome acessível: "9" sozinho não diz nada a quem usa leitor de tela. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { AppNavItem } from '@1doc/1ds-react';` ## Quando usar Dentro do `AppHeader`, como item da navegação principal do produto. ## Quando NÃO usar Como botão de ação — use `Button`. Como aba dentro de uma tela, `Tabs`. Como item de menu suspenso, `Dropdown`. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `label` | `string` | Texto do item | | `badge` | `string \| number` | Contador ao lado do rótulo | | `badgeLabel` | `string` | O que o contador significa, para leitor de tela | | `active` | `boolean` | Item da área aberta | | `hasMenu` | `boolean` | Desenha a seta de menu | | `expanded` | `boolean` | Estado do menu, quando `hasMenu` | | `icon` | `IconProp` | Ícone antes do rótulo | | `className` | `string` | Classes CSS adicionais | | `onClick` | `() => void` | Callback ao acionar | | `children` | `any` | Conteúdo alternativo ao `label`. | ## Exemplo ```tsx import { AppNavItem } from '@1doc/1ds-react'; Exemplo AppNavItem ``` --- # AppShell > AppShell — a moldura da aplicação: cabeçalho no topo, barra lateral à esquerda, conteúdo preenchendo o resto. Existe porque o padrão de layout da 1Doc estava escrito e mesmo assim cada produto o reconstruía do zero — foi a maior lacuna apontada pela auditoria interna (dimensão "cobertura de escopo", nota 4 de 10). O protótipo da 1Doc gastava ~1.000 linhas entre `App.tsx`, `Header.tsx` e CSS para chegar aqui. O que ele resolve e ninguém precisa mais escrever: - o cabeçalho e a barra **não rolam**; só o conteúdo rola; - a área de conteúdo nunca estoura na horizontal (`min-width: 0`, que é a linha que falta em toda implementação manual e deixa tabela larga empurrar o layout inteiro); - a barra lateral encolhe e cresce sem empurrar o conteúdo aos saltos. Ele não decide o que vai dentro: cabeçalho, barra e conteúdo entram por slot. O DS desenha a moldura; o produto diz o que é o logo, o menu e a tela. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { AppShell } from '@1doc/1ds-react';` ## Quando usar Como raiz de uma aplicação com cabeçalho fixo e navegação lateral. É o esqueleto da tela inteira, usado uma vez por app. ## Quando NÃO usar Em página solta, tela de login ou conteúdo embutido em outro sistema — ali o layout é da página, não do app. Para agrupar conteúdo dentro de uma tela, use `Box`, `Stack` ou `Container`. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `className` | `string` | Classes CSS adicionais | | `header` | `any` | Cabeçalho fixo no topo (normalmente um `AppHeader`). | | `sidebar` | `any` | Barra lateral à esquerda (normalmente um `AppSidebar`). | | `children` | `any` | Conteúdo da tela — é a única parte que rola. | ## Exemplo ```tsx import { AppShell } from '@1doc/1ds-react'; Exemplo AppShell ``` --- # AppSidebar > AppSidebar — a navegação lateral da aplicação, que abre e fecha. Fechada tem 48px e mostra só ícones; aberta tem 248px e mostra ícone mais rótulo. É o padrão 1Doc, que estava escrito e era reconstruído à mão em cada produto. O detalhe que quase toda implementação manual erra: **com a barra fechada, o rótulo continua no HTML**, só fica invisível. Trocar o texto por um ícone solto deixa a navegação inteira muda para quem usa leitor de tela — e é o que acontece quando se resolve o "fechado" escondendo o `` com `display: none`. O rodapé é slot livre: é onde vai a marca do parceiro, que é conteúdo do produto e não do design system. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { AppSidebar } from '@1doc/1ds-react';` ## Quando usar Navegação principal de uma aplicação, dentro de um `AppShell`. Os itens são as áreas do produto, não as etapas de um fluxo. ## Quando NÃO usar Para alternar entre visões de uma MESMA tela — use `Tabs`. Para um painel lateral que abre sobre o conteúdo e fecha, o DS ainda não tem `Drawer`. Para menu de ações, `Dropdown`. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `items` | `AppSidebarItem[]` | Itens de navegação | | `activeId` | `string` | Id do item ativo (vira aria-current) | | `collapsed` | `boolean` | Barra fechada (só ícones) | | `toggleable` | `boolean` | Mostra o botão de abrir/fechar | | `ariaLabel` | `string` | Nome acessível da navegação | | `className` | `string` | Classes CSS adicionais | | `onSelect` | `(id: string) => void` | Callback ao acionar um item (recebe o id) | | `onToggle` | `(collapsed: boolean) => void` | Callback do botão de abrir/fechar (recebe o novo estado) | | `footer` | `any` | Rodapé livre — marca do parceiro, versão, o que o produto quiser. | ## Tipos auxiliares Exportados pelo mesmo pacote e necessários para montar as props de coleção. ```ts export interface AppSidebarItem { /** Identificador do item — é o que volta em `onSelect`. */ id: string; /** Rótulo. Continua existindo para leitor de tela com a barra fechada. */ label: string; /** Ícone Font Awesome como objeto importado. */ icon?: IconProp; /** Contador ao lado do rótulo (ex.: não lidos). */ badge?: string | number; /** Desabilita o item. */ disabled?: boolean; } ``` ## Exemplo ```tsx import { AppSidebar } from '@1doc/1ds-react'; ``` --- # AppSubheader > AppSubheader — a segunda barra da aplicação, logo abaixo do `AppHeader`. É a barra de **contexto**: onde o usuário está (trilha) e o que ele pode fazer a partir daí (busca, seletor de setor, ações rápidas). Mais baixa que o cabeçalho de propósito — 42px contra 56px — porque é informação de apoio, não a identidade do produto. Aparece em praticamente toda tela da 1Doc e era reconstruída à mão. Como o `AppHeader`, ela desenha a barra e distribui as regiões; o conteúdo é do produto. A trilha normalmente é um `Breadcrumb` do próprio DS. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { AppSubheader } from '@1doc/1ds-react';` ## Quando usar Abaixo do `AppHeader`, para trilha de navegação e ações de contexto que valem para a tela inteira. ## Quando NÃO usar Para o título e as ações de UMA tela — isso é `PageHeader`, que vive dentro do conteúdo e rola com ele. Esta barra fica parada e é do app. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `className` | `string` | Classes CSS adicionais | | `actions` | `any` | Região direita: busca, seletor de setor, ações rápidas. | | `children` | `any` | Região esquerda — normalmente um `Breadcrumb`. | ## Exemplo ```tsx import { AppSubheader } from '@1doc/1ds-react'; Exemplo AppSubheader ``` --- # Avatar > Representação visual de uma pessoa ou entidade. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { Avatar } from '@1doc/1ds-react';` ## Quando usar Representar pessoa ou entidade por foto, iniciais ou ícone. `AvatarGroup` empilha vários com contador de excedente. ## Quando NÃO usar Para ilustrar conceito ou ação — use `Icon`. Para a marca do produto, use `Logo`. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `src` | `string` | URL da imagem. Se fornecida, o tipo será automaticamente 'Photo' visualmente. O componente NÃO faz fallback automático quando a imagem falha ao carregar: ele emite `onError` e o consumidor decide (ex.: limpar o `src` para exibir as iniciais via `children`). | | `alt` | `string` | Texto alternativo para a imagem (acessibilidade). | | `size` | `"xs" \| "sm" \| "md" \| "lg"` | Tamanho do avatar. XS: 16px, SM: 24px, MD: 42px, LG: 64px. | | `type` | `"photo" \| "letter" \| "number"` | Tipo do avatar. Controla estilos de cor. | | `children` | `any` | Conteúdo interno (Iniciais ou Número). Ex: "AB", "+3". | | `className` | `string` | Classes adicionais. | | `title` | `string` | Texto de dica exibido no hover (atributo `title`). | | `ariaLabel` | `string` | Rótulo acessível do avatar (atributo `aria-label`). Prop camelCase (nao "aria-label" com hifen): o gerador Vue do Mitosis nao serializa acesso via props["aria-label"] e emitiria a string literal. | | `onError` | `(event?: any) => void` | Chamado quando a imagem falha ao carregar. O parametro e opcional: o Mitosis injeta o evento nativo do na geracao React, entao a assinatura precisa aceitar um argumento opcional para o handler gerado ser atribuivel e nao virar implicit-any. | ## Exemplo ```tsx import { Avatar } from '@1doc/1ds-react'; Exemplo Avatar ``` --- # Badge > Componente Badge para exibir status, rótulos e contagens. Suporta múltiplas variantes de cor, tamanhos e estilos. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { Badge } from '@1doc/1ds-react';` ## Quando usar Contagem ou marcador CURTO sobreposto/adjacente a outro elemento: número de não lidos, "Novo". ## Quando NÃO usar Para rótulo de categoria ou status com texto — use `Tag`. Para item removível, use `Chips`. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `variant` | `"neutral" \| "positive" \| "negative" \| "info" \| "primary"` | Variação de cor semântica. | | `size` | `"sm" \| "md" \| "lg" \| "xs" \| "pill"` | Tamanho do badge. | | `appearance` | `"solid" \| "soft" \| "outlined"` | Estilo visual do badge. | | `iconLeft` | `any` | Conteúdo do ícone à esquerda. - React: Passe um elemento React (ex: ``). - Vue: Utilize o slot `#icon-left`. | | `iconRight` | `any` | Conteúdo do ícone à direita. - React: Passe um elemento React (ex: ``). - Vue: Utilize o slot `#icon-right`. | | `className` | `string` | Classes CSS adicionais. | | `id` | `string` | Id aplicado ao elemento raiz do badge. | | `children` | `any` | Conteúdo textual do badge. | ## Exemplo ```tsx import { Badge } from '@1doc/1ds-react'; Exemplo Badge ``` --- # BottomNavigation > BottomNavigation — barra de navegação inferior mobile-first (achado do time mobile na simulação de adoção: Tabs não serve para bottom-nav sem hackear classes internas — indicador embaixo, sem ícone acima do label, itens sem flex:1). Itens com ícone acima do label, indicador NO TOPO do item ativo, alvos de toque ≥44px por padrão. Controlado (value/onChange) ou não-controlado (defaultValue). - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { BottomNavigation } from '@1doc/1ds-react';` ## Quando usar Barra FIXA no rodapé para navegar entre as áreas principais do app mobile (Inbox, Novo, Início, Listar, Notificações). Tipicamente 3 a 5 itens. ## Quando NÃO usar Para alternar conteúdo dentro de uma página — use `Tabs`. Em desktop, a navegação principal é a sidebar, não este componente. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `items` | `BottomNavigationItem[]` | Itens da barra | | `value` | `string` | Key do item ativo (controlado) | | `defaultValue` | `string` | Key inicial (não-controlado) | | `fixed` | `boolean` | Fixa a barra no rodapé da viewport @default true | | `activeStyle` | `"indicator" \| "raised"` | Como o item ativo se destaca. **O padrão é `raised`.** `raised` põe o ícone do ativo dentro de um disco cheio que SOBE acima da barra — é o menu do app mobile da 1Doc (Handoff, nó 5518:2292), e por isso é o padrão: quem consome este DS quer esse menu, não o outro. `indicator` desenha a barra no topo do item, para produtos que não seguem o desenho do app. | | `ariaLabel` | `string` | Nome acessível da navegação @default 'Navegação principal' | | `className` | `string` | — | | `onChange` | `(key: string) => void` | Callback com a key do item selecionado | ## Tipos auxiliares Exportados pelo mesmo pacote e necessários para montar as props de coleção. ```ts export interface BottomNavigationItem { key: string; label: string; icon?: IconProp; disabled?: boolean; } ``` ## Exemplo ```tsx import { BottomNavigation } from '@1doc/1ds-react'; ``` --- # BottomSheet > Painel que entra por baixo, para fluxos de mobile. Componente próprio em vez de variante do Modal: a identidade dele é gesto — alça, arrastar para fechar, alturas de encaixe — e isso não caberia em prop do Modal sem dar duas personalidades ao componente. Mas NÃO reimplementa overlay: usa a mesma pilha (`utils/overlay-stack`), a mesma camada (`--umds-semantic-layer-modal`) e o mesmo backdrop do Modal, para o comportamento de sobreposição não divergir. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { BottomSheet } from '@1doc/1ds-react';` ## Quando usar Painel que sobe pela borda INFERIOR, com alça e encaixes opcionais. É o padrão mobile para escolher opções, filtrar ou ver detalhe sem sair da tela. ## Quando NÃO usar Em desktop, para diálogo centralizado — use `Modal`. Para confirmação curta de sim/não — use `ConfirmDialog`. Para menu curto ancorado a um gatilho — use `Dropdown`. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `closeLabel` | `string` | Rótulo acessível do botão de fechar. @default 'Fechar' | | `open` | `boolean` | — | | `onClose` | `(event?: any) => void` | — | | `title` | `string` | Título no topo. Sem ele, informe `ariaLabel`. | | `footer` | `any` | Barra inferior fixa. Flutua sobre o conteúdo, com sombra própria. | | `snapPoints` | `Array` | Alturas de encaixe como fração da viewport, da menor para a maior. Com um valor só, o painel tem altura fixa. Sem a prop, ajusta ao conteúdo até 90% da tela. | | `defaultSnap` | `number` | Índice do encaixe inicial em `snapPoints`. | | `grabber` | `boolean` | Alça visível no topo. | | `closable` | `boolean` | Botão de fechar no cabeçalho. | | `closeOnEsc` | `boolean` | — | | `closeOnBackdrop` | `boolean` | — | | `ariaLabel` | `string` | — | | `ariaLabelledby` | `string` | — | | `className` | `string` | — | | `id` | `string` | — | | `children` | `any` | — | | `style` | `any` | — | ## Exemplo ```tsx import { BottomSheet } from '@1doc/1ds-react'; Exemplo BottomSheet ``` --- # Box > Box — superfície com padding, fundo, borda e raio vindos dos tokens. É a caixa genérica do DS. Existe para evitar o `
` escrito à mão: cada valor sai da escala oficial, não da memória de quem escreve. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { Box } from '@1doc/1ds-react';` ## Quando usar Agrupar conteúdo numa superfície com respiro e fundo: painel de filtros, bloco de resumo, área destacada dentro de uma tela. ## Quando NÃO usar Para um item de listagem com título, ações e elevação própria — use `Card`, que já tem essa anatomia. Para só distribuir filhos no eixo sem desenhar nada, use `Stack`. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `padding` | `BoxSpacing` | Padding em todos os lados, na escala do DS | | `paddingX` | `BoxSpacing` | Padding horizontal (sobrescreve padding) | | `paddingY` | `BoxSpacing` | Padding vertical (sobrescreve padding) | | `background` | `"none" \| "surface" \| "muted" \| "primary-light" \| "positive-light" \| "negative-light" \| "info-light"` | Fundo semântico do DS | | `bordered` | `boolean` | Desenha borda de 1px na cor neutra | | `radius` | `"none" \| "sm" \| "pill" \| "circular"` | Raio da borda | | `shadow` | `"none" \| "level1" \| "level2" \| "level3"` | Elevação | | `fullWidth` | `boolean` | Ocupa 100% da largura disponível | | `className` | `string` | Classes CSS adicionais | | `children` | `any` | Conteúdo da caixa. | ## Exemplo ```tsx import { Box } from '@1doc/1ds-react'; Exemplo Box ``` --- # Breadcrumb > Breadcrumb component — navegação estrutural (trilha de páginas). - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { Breadcrumb } from '@1doc/1ds-react';` ## Quando usar Mostrar ONDE o usuário está na hierarquia do sistema e permitir subir de nível. Use em páginas com profundidade 2 ou mais. ## Quando NÃO usar Para progresso dentro de um fluxo de etapas — use `Stepper`. Para navegar entre seções da mesma página, use `Tabs`. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `ariaLabel` | `string` | Rótulo acessível do trilha. @default 'Navegação estrutural' | | `items` | `BreadcrumbItem[]` | Lista de itens da trilha; o último é a página atual | | `separator` | `string` | Separador entre itens (padrão '/') | | `className` | `string` | Classes CSS adicionais | ## Tipos auxiliares Exportados pelo mesmo pacote e necessários para montar as props de coleção. ```ts export interface BreadcrumbItem { label: string; href?: string; onClick?: () => void; } ``` ## Exemplo ```tsx import { Breadcrumb } from '@1doc/1ds-react'; ``` --- # Button > Button — botão de ação com variantes, tamanhos, ícones e estado de carregamento. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { Button } from '@1doc/1ds-react';` ## Quando usar AÇÃO que muda estado: salvar, enviar, abrir modal, confirmar. Use `variant="icon"` para ação só com ícone (sempre com `ariaLabel`). ## Quando NÃO usar Para NAVEGAR para outra página ou recurso — use `Link`, que gera `` e permite abrir em nova aba. A regra: se o usuário pode querer "abrir em nova aba", é `Link`. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `variant` | `"primary" \| "secondary" \| "neutral" \| "text" \| "negative" \| "negative-outlined" \| "icon"` | Variante visual: 'primary' \| 'secondary' \| 'neutral' \| 'text' \| 'negative' \| 'negative-outlined' \| 'icon' | | `size` | `"sm" \| "md" \| "lg"` | Tamanho do botão: 'sm' \| 'md' \| 'lg' | | `disabled` | `boolean` | Desabilita o botão | | `type` | `"button" \| "submit" \| "reset"` | Tipo nativo do botão: 'button' \| 'submit' \| 'reset' | | `children` | `any` | — | | `onClick` | `(event?: any) => void` | Callback disparado no clique | | `className` | `string` | Classes CSS adicionais | | `startIcon` | `IconProp` | Ícone (Font Awesome) exibido antes do texto | | `endIcon` | `IconProp` | Ícone (Font Awesome) exibido após o texto | | `loading` | `boolean` | Exibe o spinner de carregamento (marca o botão com aria-busy) | | `loadingIcon` | `IconProp` | Ícone usado como spinner (padrão: faRefresh — glifo arrows-rotate) | | `loadingPosition` | `"start" \| "end" \| "center"` | Posição do spinner: 'start' \| 'end' \| 'center' | | `fullWidth` | `boolean` | Ocupa 100% da largura do container | | `ariaLabel` | `string` | Descrição acessível do botão (vira `aria-label`). OBRIGATÓRIO se o botão não possuir texto visível (ex: icon-only). Caso não fornecido, o texto interno será usado. Prop camelCase (não "aria-label" com hífen): o gerador Vue do Mitosis não serializa acesso via props["aria-label"]. | | `id` | `string` | Id nativo do botão | | `name` | `string` | Atributo `name` nativo (participação em formulários) | | `value` | `string` | Atributo `value` nativo (participação em formulários) | | `form` | `string` | Id do formulário ao qual o botão pertence | | `autoFocus` | `boolean` | Foca o botão automaticamente ao montar | | `tabIndex` | `number` | Ordem de tabulação nativa | ## Exemplo ```tsx import { Button } from '@1doc/1ds-react'; ``` --- # Card > Componente Card — container de conteúdo com header opcional. Suporta variações de padding, sombra e efeito de hover. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { Card } from '@1doc/1ds-react';` ## Quando usar Agrupar conteúdo relacionado num bloco com elevação: item de lista, resumo, painel. É a unidade visual padrão de listagem. ## Quando NÃO usar Para dados tabulares comparáveis coluna a coluna — use `DataTable`. Para só organizar em colunas, use `Grid` (Card é superfície, Grid é layout). ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `hoverable` | `boolean` | Ativa o estilo de hover (elevação de sombra e realce da borda). | | `padding` | `"none" \| "sm" \| "md" \| "lg"` | Espaçamento interno. | | `shadow` | `"none" \| "xs" \| "sm" \| "md" \| "lg"` | Intensidade da sombra. | | `title` | `string` | Título do header (ativa o card-header). | | `description` | `string` | Descrição exibida abaixo do título. | | `className` | `string` | Classes CSS adicionais. | | `children` | `any` | Conteúdo do card. | ## Exemplo ```tsx import { Card } from '@1doc/1ds-react'; Exemplo Card ``` --- # Checkbox > Componente Checkbox — caixa de seleção com suporte a estados marcado, indeterminado, inválido, sucesso e desabilitado. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { Checkbox } from '@1doc/1ds-react';` ## Quando usar Opções INDEPENDENTES, onde cada uma liga/desliga sozinha, ou um aceite único ("Li e concordo"). Suporta estado indeterminado para "marcar todos" parcial. ## Quando NÃO usar Para escolher UMA entre várias mutuamente exclusivas — use `Radio`. Para ligar/desligar uma configuração com efeito imediato, use `Switch`. Para muitas opções numa lista, use `MultiSelect`. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `checked` | `boolean` | Estado marcado controlado | | `defaultChecked` | `boolean` | Estado marcado inicial (não controlado) | | `disabled` | `boolean` | Desabilita a caixa de seleção | | `required` | `boolean` | Marca o campo como obrigatório | | `indeterminate` | `boolean` | Estado indeterminado (visual) | | `readOnly` | `boolean` | Somente leitura: o valor não muda, mas o campo continua focável e é enviado no submit. Diferente de `disabled`, que tira das duas coisas. | | `tabIndex` | `number` | Ordem de tabulação do input nativo | | `decorative` | `boolean` | Modo PURAMENTE VISUAL: não renderiza o input nativo (nem participa de form/foco/AT). Para indicadores de seleção dentro de widgets que já têm semântica própria (ex.: options do MultiSelect com aria-selected). | | `invalid` | `boolean` | Estado de erro/inválido | | `errorMessage` | `any` | Mensagem de erro abaixo do rótulo (ativa o estado inválido) | | `success` | `boolean` | Estado de sucesso | | `size` | `"sm" \| "md" \| "lg"` | Tamanho: 'sm' \| 'md' \| 'lg' (nomenclatura padrão do 1DS) | | `background` | `boolean` | Variante com fundo destacado no label | | `name` | `string` | Atributo name do input nativo | | `value` | `string` | Atributo value do input nativo | | `id` | `string` | ID do input nativo | | `label` | `string` | Texto do rótulo | | `description` | `string` | Texto de descrição abaixo do rótulo | | `helperText` | `string` | Texto de apoio abaixo do campo. É o nome canônico na família de campos (Input, Textarea, DatePicker, TimePicker, PhoneInput, FileInput já usam). `description` continua funcionando como apelido, para não quebrar quem já escreveu — mas o nome novo é este. | | `ariaLabel` | `string` | Nome acessível quando não há label visível (vira aria-label no input). | | `className` | `string` | Classes CSS adicionais | | `onChange` | `(checked: boolean) => void` | Callback acionado ao alternar o estado (recebe o novo boolean) | ## Exemplo ```tsx import { Checkbox } from '@1doc/1ds-react'; ``` --- # Chips > Chips component — rótulo interativo compacto, usado principalmente no MultiSelect e como tags removíveis. - Framework: React - Pacote: `@1doc/1ds-react` (v2.5.0) - Import: `import { Chips } from '@1doc/1ds-react';` ## Quando usar Item REMOVÍVEL que representa uma escolha já feita pelo usuário: valor selecionado dentro de um MultiSelect, filtro aplicado que pode ser desfeito, destinatário adicionado a um campo. Também serve como filter chip acionável (`selected` + `onClick`). ## Quando NÃO usar Para rótulo apenas informativo que o usuário não remove nem aciona — use `Tag`. A regra prática: se não há `onRemove` nem `onClick`, o componente certo é `Tag`. ## Props | Prop | Tipo | Descrição | | --- | --- | --- | | `label` | `string` | Texto exibido no chip (obrigatório) | | `removable` | `boolean` | Exibe o botão × para remover o chip | | `disabled` | `boolean` | Desabilita o chip (visual esmaecido e sem interação) | | `size` | `"sm" \| "md"` | Tamanho do chip: 'sm' \| 'md' | | `variant` | `"default" \| "primary" \| "positive" \| "negative" \| "info"` | Variante visual: 'default' \| 'primary' \| 'positive' \| 'negative' \| 'info' | | `selected` | `boolean` | Estado selecionado (filter chip) — vira aria-pressed | | `className` | `string` | Classes CSS adicionais | | `onClick` | `(event: any) => void` | Torna o chip acionável (filter chip): o label vira um