Avançados: essenciais

Toggles, label, regiões expansíveis, menus disparados por interação e a paleta de comandos. A fatia que quase toda tela usa em algum momento.

Toggle

Botão de dois estados — como um checkbox estilizado de botão. Controlado (pressed + onPressedChange) ou não-controlado (defaultPressed).

import { Toggle } from "tempest-react-sdk";

<Toggle
  defaultPressed
  variant="outline"
  size="md"
  onPressedChange={(pressed) => console.log(pressed)}
>
  Negrito
</Toggle>;

Prop	Tipo	Default	Descrição
pressed	boolean	—	Estado controlado. Quando definido, vira controlado
defaultPressed	boolean	false	Estado inicial no modo não-controlado
onPressedChange	(pressed: boolean) => void	—	Disparado com o próximo estado ao ativar
size	"sm" \| "md" \| "lg"	"md"	Tamanho visual
variant	"default" \| "outline"	"default"	Estilo visual

Demais props de <button> são repassadas.

A11y

Renderiza um <button type="button"> nativo expondo o estado via aria-pressed e data-state="on"|"off".

ToggleGroup (+ ToggleGroupItem)

Conjunto de toggles que compartilham estado de seleção via contexto. Modo single (valor string) ou multiple (valor string[]).

import { ToggleGroup, ToggleGroupItem } from "tempest-react-sdk";

<ToggleGroup type="single" defaultValue="left" onValueChange={(value) => console.log(value)}>
  <ToggleGroupItem value="left">Esquerda</ToggleGroupItem>
  <ToggleGroupItem value="center">Centro</ToggleGroupItem>
  <ToggleGroupItem value="right">Direita</ToggleGroupItem>
</ToggleGroup>;

ToggleGroup:

Prop	Tipo	Default	Descrição
type	"single" \| "multiple"	"single"	single mantém um valor; multiple mantém um conjunto
value	string \| string[]	—	Valor controlado (string para single, string[] multi)
defaultValue	string \| string[]	—	Valor inicial não-controlado
onValueChange	(value: string \| string[]) => void	—	Disparado com o próximo valor
children	ReactNode	—	Itens ToggleGroupItem

ToggleGroupItem:

Prop	Tipo	Default	Descrição
value	string	—	Valor estável que identifica o item
disabled	boolean	—	Desabilita o item
children	ReactNode	—	Conteúdo do item

Single mode

Em single, onValueChange recebe "" (string vazia) quando nada está selecionado.

Label

Um <label> de formulário. Associe a um controle via htmlFor. Com required, anexa um asterisco decorativo (aria-hidden).

import { Label } from "tempest-react-sdk";

<Label htmlFor="email" required>
  E-mail
</Label>;

Prop	Tipo	Default	Descrição
required	boolean	false	Anexa um asterisco em cor de perigo marcando campo obrigatório

Demais props de <label> (incl. htmlFor) são repassadas.

Collapsible

Uma única região expandir/recolher — alternativa mais leve ao Accordion para um bloco. Controlado (open + onOpenChange) ou não-controlado (defaultOpen).

import { Collapsible } from "tempest-react-sdk";

<Collapsible trigger="Ver detalhes" defaultOpen={false}>
  <p>Conteúdo revelado ao expandir.</p>
</Collapsible>;

Prop	Tipo	Default	Descrição
open	boolean	—	Estado controlado. Quando definido, vira controlado
defaultOpen	boolean	false	Estado inicial não-controlado
onOpenChange	(open: boolean) => void	—	Disparado com o próximo estado ao ativar o gatilho
trigger	ReactNode	—	Conteúdo renderizado dentro do botão gatilho
children	ReactNode	—	Conteúdo recolhível, oculto enquanto fechado

A11y

O gatilho é um <button aria-expanded aria-controls> ligado a uma role="region" de mesmo id; a região fica hidden enquanto fechada.

ContextMenu

Menu de clique direito. Abre na posição do cursor via onContextMenu (menu nativo suprimido), renderizado por um Portal. Fecha no clique fora, Escape ou seleção.

import { ContextMenu } from "tempest-react-sdk";

<ContextMenu
  items={[
    { label: "Editar", onSelect: () => edit() },
    { label: "Duplicar", onSelect: () => duplicate() },
    { separator: true },
    { label: "Excluir", danger: true, onSelect: () => remove() },
  ]}
>
  <div>Clique direito aqui</div>
</ContextMenu>;

Prop	Tipo	Default	Descrição
items	ContextMenuItem[]	—	Entradas do menu — itens selecionáveis e separadores
children	ReactNode	—	Área de gatilho; clique direito em qualquer parte abre
className	string	—	Classes extras repassadas ao elemento do menu

ContextMenuItem = { label: ReactNode; onSelect?: () => void; disabled?: boolean; danger?: boolean } ou { separator: true }.

Teclado

Setas ↑/↓ movem o foco entre itens selecionáveis; Enter ativa o item focado.

HoverCard

Pré-visualização de conteúdo exibida ao passar o mouse ou focar o gatilho. Abre após openDelay, fecha após closeDelay.

import { HoverCard } from "tempest-react-sdk";

<HoverCard trigger={<a href="/u/maria">@maria</a>} placement="bottom">
  <div>
    <strong>Maria Silva</strong>
    <p>Engenheira de software · 2.3k seguidores</p>
  </div>
</HoverCard>;

Prop	Tipo	Default	Descrição
trigger	ReactNode	—	Elemento que o usuário foca/aponta para revelar
children	ReactNode	—	Conteúdo do card
openDelay	number (ms)	300	Atraso antes de abrir em mouseenter/focus
closeDelay	number (ms)	150	Atraso antes de fechar em mouseleave/blur
placement	"top" \| "bottom" \| "left" \| "right"	"bottom"	Ancoragem do card relativa ao gatilho

A11y

O card é uma role="dialog" rotulada; o gatilho permanece focável por teclado.

Command (paleta ⌘K)

Paleta de comandos estilo ⌘K: diálogo em overlay com input que filtra itens por substring (label + keywords), agrupa resultados e suporta navegação por teclado (↑/↓, Enter, Escape). Prende o foco enquanto aberto.

import { Command } from "tempest-react-sdk";
import { useState } from "react";

const [open, setOpen] = useState(false);

<Command
  open={open}
  onOpenChange={setOpen}
  placeholder="Digite um comando…"
  items={[
    { id: "new", label: "Novo documento", group: "Arquivo", onSelect: () => create() },
    {
      id: "open",
      label: "Abrir…",
      group: "Arquivo",
      keywords: ["recente"],
      onSelect: () => openFile(),
    },
    { id: "theme", label: "Alternar tema", group: "Preferências", onSelect: () => toggleTheme() },
  ]}
/>;

Prop	Tipo	Default	Descrição
open	boolean	—	Se a paleta está visível
onOpenChange	(open: boolean) => void	—	Próximo estado (Escape, seleção, clique no backdrop)
items	CommandItem[]	—	Candidatos a filtrar e exibir
placeholder	string	"Type a command…"	Placeholder do input de busca
emptyMessage	ReactNode	"No results"	Exibido quando nada combina com a busca
className	string	—	Repassado ao elemento de diálogo

CommandItem = { id: string; label: string; group?: string; keywords?: string[]; onSelect: () => void; icon?: ReactNode }.

Gatilho global

Combine com useKeyboardShortcut("mod+k", () => setOpen(true)) para abrir via ⌘K / Ctrl+K.

Recap

• Essenciais: Toggle/ToggleGroup para estados pressionáveis, Label para formulários, Collapsible para um bloco expansível, ContextMenu/HoverCard para overlays disparados por interação e Command para a paleta ⌘K.
• Todos seguem os mesmos padrões controlado/não-controlado, expõem A11y por teclado e importam de tempest-react-sdk.