@softize/opus 18.5.0 → 20.0.0

package/src/ui/docs/content/calendar.md

@@ -1,10 +1,11 @@
-O calendário fala pt-BR por padrão: nomes de mês e de dia vêm do `locale` (`ptBR` de
-`date-fns/locale`) e os controles de navegação têm rótulos acessíveis em português. Passe outro
-`locale` para trocar o idioma; `labels` sobrescreve rótulos individualmente.
-
 ## Dia único
 
-mode=single guarda uma Date — controle por selected/onSelect. defaultMonth abre o calendário no mês certo sem mexer na seleção.
+Use `Calendar` quando a pessoa precisar escolher datas vendo o mês inteiro, como a data de uma
+entrega ou a janela de um relatório. Para abrir o calendário a partir de um campo, ancore-o em um
+[`Popover`](/ui/popover).
+
+Com `mode="single"`, a seleção é uma `Date`, controlada por `selected` e `onSelect`. `defaultMonth`
+abre o calendário no mês desejado sem alterar a seleção.
 
 ```tsx preview
 const [day, setDay] = useState<Date | undefined>(new Date(2026, 5, 22))
@@ -19,9 +20,14 @@ render(
 )
 ```
 
+O calendário usa pt-BR por padrão: os nomes de mês e de dia vêm do `locale` (`ptBR`, de
+`date-fns/locale`) e os controles de navegação têm nomes acessíveis em português. Passe outro
+`locale` para trocar o idioma; `labels` substitui nomes acessíveis individualmente.
+
 ## Intervalo
 
-mode=range guarda { from, to } — o padrão para filtrar sessões por janela de datas. O primeiro clique fixa o início; o segundo, o fim.
+Com `mode="range"`, a seleção é um intervalo `{ from, to }`, o formato comum para filtrar registros
+por período. O primeiro clique define o início e o segundo, o fim.
 
 ```tsx preview
 const [week, setWeek] = useState<DateRange | undefined>({
@@ -39,9 +45,73 @@ render(
 )
 ```
 
-## Navegação por dropdown
+Para um intervalo que atravessa meses, `numberOfMonths` mostra meses lado a lado.
+
+```tsx preview
+const [range, setRange] = useState<DateRange | undefined>({
+  from: new Date(2026, 5, 24),
+  to: new Date(2026, 6, 8),
+})
+
+render(
+  <Calendar
+    mode="range"
+    numberOfMonths={2}
+    selected={range}
+    onSelect={setRange}
+    defaultMonth={new Date(2026, 5, 1)}
+  />,
+)
+```
+
+## Vários dias
 
-captionLayout=dropdown troca o título do mês por seletores de mês e ano — bom para pular para um período distante (ex.: histórico de um repositório) sem clicar mês a mês.
+Com `mode="multiple"`, a seleção é uma lista de datas, e cada clique marca ou desmarca um dia. Use
+esse modo quando os dias escolhidos não formarem um intervalo contínuo, como os plantões de uma
+equipe.
+
+```tsx preview
+const [days, setDays] = useState<Date[] | undefined>([
+  new Date(2026, 5, 3),
+  new Date(2026, 5, 10),
+  new Date(2026, 5, 17),
+])
+
+render(
+  <Calendar
+    mode="multiple"
+    selected={days}
+    onSelect={setDays}
+    defaultMonth={new Date(2026, 5, 1)}
+  />,
+)
+```
+
+## Datas indisponíveis
+
+`disabled` impede a escolha de datas específicas. Ele aceita uma data, uma lista, um intervalo
+`{ from, to }`, um predicado ou combinações como `{ before: data }` e `{ dayOfWeek: [0, 6] }`. No
+exemplo, dias anteriores a 10 de junho e fins de semana ficam indisponíveis.
+
+```tsx preview
+const [day, setDay] = useState<Date | undefined>()
+
+render(
+  <Calendar
+    mode="single"
+    selected={day}
+    onSelect={setDay}
+    defaultMonth={new Date(2026, 5, 1)}
+    disabled={[{ before: new Date(2026, 5, 10) }, { dayOfWeek: [0, 6] }]}
+  />,
+)
+```
+
+## Navegação por seletores
+
+`captionLayout="dropdown"` troca o título do mês por seletores de mês e ano. Use essa forma quando a
+pessoa precisar chegar a um período distante, como o histórico de anos anteriores, sem avançar mês
+a mês.
 
 ```tsx preview
 <Calendar
@@ -51,25 +121,63 @@ captionLayout=dropdown troca o título do mês por seletores de mês e ano — b
 />
 ```
 
+## Personalizar o dia
+
+Cada dia é um `CalendarDayButton`: um `Button` `ghost` quadrado que recebe os modificadores do dia,
+como `selected`, `range_start` e `today`, e cuida do foco e dos estados de seleção. Para decorar o
+dia, como marcar datas com evento, substitua o componente por `components={{ DayButton: … }}` e
+renderize `CalendarDayButton` por dentro, em vez de reimplementar esse comportamento.
+
+```tsx preview
+const eventDays = [5, 12, 26]
+
+render(
+  <Calendar
+    mode="single"
+    defaultMonth={new Date(2026, 5, 1)}
+    components={{
+      DayButton: ({ children, ...props }) => (
+        <CalendarDayButton {...props}>
+          {children}
+          {eventDays.includes(props.day.date.getDate()) &&
+            props.day.date.getMonth() === 5 && (
+              <span aria-hidden="true" className="size-1 rounded-full bg-primary" />
+            )}
+        </CalendarDayButton>
+      ),
+    }}
+  />,
+)
+```
+
+O marcador do exemplo é decorativo. Quando a informação importar para a decisão, inclua-a também
+no nome acessível do dia por `labels.labelDayButton`.
+
 ## Propriedades de Calendar
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `mode` | `'single' \| 'multiple' \| 'range'` | | O tipo de seleção — define o formato de selected/onSelect (Date, Date[] ou { from, to }). |
-| `selected` | `Date \| Date[] \| DateRange` | | A seleção atual no modo controlado — o formato segue o mode. Pareie com onSelect. |
-| `onSelect` | `(selected) => void` | | Chamado quando o usuário escolhe uma data. O argumento segue o mode. |
-| `defaultMonth` | `Date` | | O mês exibido ao montar, sem afetar a seleção. |
-| `captionLayout` | `'label' \| 'dropdown' \| 'dropdown-months' \| 'dropdown-years'` | `'label'` | Como o título do mês aparece — label é texto fixo; dropdown vira seletores de mês e ano. |
-| `numberOfMonths` | `number` | `1` | Quantos meses mostrar lado a lado — útil para escolher um intervalo longo. |
-| `disabled` | `Matcher` | | Datas não selecionáveis — uma Date, um array, um { from, to } ou um predicado (date) => boolean. |
-| `buttonVariant` | `Button['variant']` | `'ghost'` | A variante dos botões de navegação (anterior/próximo). |
-| `showOutsideDays` | `boolean` | `true` | Mostra os dias do mês vizinho que completam a primeira e a última semana. |
-| `locale` | `Locale` | `ptBR` | Idioma dos nomes de mês e de dia (um locale do date-fns). |
-| `labels` | `Partial<Labels>` | rótulos em pt-BR | Rótulos acessíveis da navegação e dos seletores; mescla sobre o padrão. |
-
-## Personalizar o dia com CalendarDayButton
-
-Cada dia é um `CalendarDayButton` — um `Button` ghost quadrado que recebe os modificadores do
-dia (`selected`, `range-start`, `today`…). Use `components={{ DayButton: … }}` para
-decorar o dia (um marcador de evento, por exemplo) partindo dele em vez de reimplementar o
-foco e a seleção.
+| `mode` | `'single' \| 'multiple' \| 'range'` | | Tipo de seleção. Define o formato de `selected` e `onSelect`: `Date`, `Date[]` ou `{ from, to }`. |
+| `selected` | `Date \| Date[] \| DateRange` | | Seleção atual no modo controlado, no formato do `mode`. Use com `onSelect`. |
+| `onSelect` | `(selected) => void` | | Chamado quando a pessoa escolhe uma data. O argumento segue o formato do `mode`. |
+| `defaultMonth` | `Date` | | Mês exibido ao montar, sem afetar a seleção. |
+| `captionLayout` | `'label' \| 'dropdown' \| 'dropdown-months' \| 'dropdown-years'` | `'label'` | Apresentação do título do mês: texto fixo ou seletores de mês, de ano ou de ambos. |
+| `numberOfMonths` | `number` | `1` | Quantidade de meses exibidos lado a lado. |
+| `disabled` | `Matcher \| Matcher[]` | | Datas que não podem ser escolhidas: uma data, uma lista, um intervalo, um predicado ou regras como `{ before }` e `{ dayOfWeek }`. |
+| `buttonVariant` | `ButtonVariant` | `'ghost'` | Variante dos botões de mês anterior e próximo mês. |
+| `showOutsideDays` | `boolean` | `true` | Mostra os dias dos meses vizinhos que completam a primeira e a última semana. |
+| `locale` | `Locale` | `ptBR` | Idioma dos nomes de mês e de dia, como um locale do date-fns. |
+| `labels` | `Partial<Labels>` | nomes em pt-BR | Nomes acessíveis da navegação, dos seletores e dos dias; mesclados sobre o padrão. |
+| `components` | `Partial<CustomComponents>` | | Substitui partes da grade, como `DayButton`. |
+
+`Calendar` repassa as demais propriedades ao `DayPicker` do react-day-picker.
+
+## Propriedades de CalendarDayButton
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `day` | `CalendarDay` | | O dia renderizado; `day.date` é a data. Recebido do `Calendar`. |
+| `modifiers` | `Modifiers` | | Estados do dia, como `selected`, `today`, `disabled`, `range_start` e `range_end`. Recebido do `Calendar`. |
+| `className` | `string` | | Classes somadas ao botão do dia. |
+
+`CalendarDayButton` aceita também as props nativas de `<button>`, repassadas pelo `Calendar`.

package/src/ui/docs/content/card.md

@@ -1,75 +1,292 @@
-## Box simples
+## Caixa simples
 
-O uso mais comum: a superfície de conteúdo em repouso (`rounded-xl` + `border`), flat por padrão, com o padding pelo `className`. O Card não força flex/gap/padding — você compõe o miolo (sem brigar com `space-y`/`flex` seu). Quando a hierarquia realmente pedir elevação, declare a intensidade explicitamente, por exemplo `className="shadow-sm"`.
+O uso mais comum é a superfície em repouso: raio, borda e fundo, sem sombra. O `Card` não impõe
+flex, gap nem padding, então o miolo continua seu — inclusive o `space-y` ou o grid que a tela já
+usa. Nesse formato o recuo vem do `className`.
 
 ```tsx preview col
 <Card className="p-4">
-  <p className="text-sm text-muted-foreground">3 sessões ativas neste momento.</p>
+  <p className="text-sm text-muted-foreground">3 veículos aguardando retirada.</p>
 </Card>
 ```
 
-## Estruturado (header / conteúdo / rodapé)
+Quando a hierarquia realmente pedir elevação, declare a intensidade, por exemplo
+`className="shadow-sm"`.
 
-Para painel com estrutura: cada slot é dono do próprio padding (como o Dialog). CardTitle/CardDescription no header; CardFooter alinha as ações.
+## Cabeçalho, corpo e rodapé
+
+Quando o card tem estrutura, cada região vira um slot e traz o próprio recuo. `CardHeader`
+reconhece quatro slots — `CardMedia`, `CardTitle`, `CardDescription` e `CardAction` — e monta a
+linha sozinho: mídia, título e descrição de um lado, ações no extremo oposto. A ordem em que os
+slots são escritos não altera a posição.
 
 ```tsx preview col
 <Card>
   <CardHeader>
-    <CardTitle>Empresa X</CardTitle>
-    <CardDescription>2 repositórios · 3 agentes vinculados.</CardDescription>
+    <CardTitle>Oficina Centro</CardTitle>
+    <CardDescription>4 boxes · 2 consultores de plantão.</CardDescription>
   </CardHeader>
   <CardBody>
-    <p className="text-sm text-muted-foreground">Última sessão concluída há 2 horas.</p>
+    <p className="text-sm text-muted-foreground">Próximo horário livre hoje, às 14h.</p>
   </CardBody>
-  <CardFooter className="gap-2">
-    <Button size="sm">Abrir sessão</Button>
-    <Button size="sm" variant="outline">Ver repositórios</Button>
+  <CardFooter>
+    <Button size="sm" variant="outline">Ver agenda</Button>
+    <Button size="sm">Agendar revisão</Button>
   </CardFooter>
 </Card>
 ```
 
-## Com divisor
+O rodapé alinha as ações no fim da linha. Um nó que não seja um desses quatro slots dentro do
+`CardHeader` interrompe a renderização com um erro: a linha do cabeçalho pertence à família, e um
+`div` solto ali devolveria à tela a decisão de posicionamento. Conteúdo livre vai para `CardBody`.
+
+## Escolher entre contínuo e seccionado
+
+`layout` declara a anatomia da superfície inteira e fica no root. Não é uma borda ligada ou
+desligada: cada valor é um pacote de recuo, ritmo vertical, escala do título e divisores.
 
-`border-b` no header / `border-t` no footer dão o divisor quando a estrutura pede separação visível. A aresta externa e os divisores internos usam o mesmo vocabulário de `border`.
+| Aspecto | `continuous` (padrão) | `sectioned` |
+| --- | --- | --- |
+| Divisores | nenhum | entre as regiões vizinhas |
+| Ritmo vertical | o cabeçalho se aproxima do corpo; o espaço separa | regiões simétricas; o divisor separa |
+| Recuo lateral | mais folgado, para leitura | o mesmo das demais superfícies de operação |
+| Escala do título | um degrau acima | um degrau mais contida |
+
+Use `continuous` no card de leitura, que apresenta um assunto e termina. Use `sectioned` quando o
+card for uma superfície de operação — regiões com pesos diferentes, lista dentro do corpo, rodapé
+com ações — ou quando ele precisar conviver com um [`Dialog`](/ui/dialog), um
+[`Drawer`](/ui/drawer) ou um [`Pane`](/ui/pane) sem degrau visível entre eles.
 
 ```tsx preview col
-<Card>
-  <CardHeader className="border-b">
-    <CardTitle>Skill code-style</CardTitle>
-    <CardDescription>Padrão softize de código e microcopy.</CardDescription>
+render(
+  <div className="grid grid-cols-2 gap-4">
+    <Card>
+      <CardHeader>
+        <CardTitle>Contínuo</CardTitle>
+        <CardDescription>O espaço separa as regiões.</CardDescription>
+      </CardHeader>
+      <CardBody>
+        <p className="text-sm text-muted-foreground">Um assunto, lido de cima a baixo.</p>
+      </CardBody>
+      <CardFooter>
+        <Button size="sm" variant="outline">Abrir</Button>
+      </CardFooter>
+    </Card>
+    <Card layout="sectioned">
+      <CardHeader>
+        <CardTitle>Seccionado</CardTitle>
+        <CardDescription>O divisor separa as regiões.</CardDescription>
+      </CardHeader>
+      <CardBody>
+        <p className="text-sm text-muted-foreground">Regiões com pesos diferentes.</p>
+      </CardBody>
+      <CardFooter>
+        <Button size="sm" variant="outline">Abrir</Button>
+      </CardFooter>
+    </Card>
+  </div>,
+);
+```
+
+### Os divisores são derivados
+
+Em `sectioned`, cada região desenha a própria linha quando existe uma região vizinha do outro lado.
+Um cabeçalho sozinho não fecha nada, um rodapé que é a única região também não, e um cabeçalho
+seguido direto de um rodapé produz uma linha só, em vez de duas encostadas.
+
+Por isso, não escreva `border-b` no cabeçalho nem `border-t` no rodapé: a regra depende da presença
+das regiões irmãs, que o componente conhece e a tela não. Uma borda escrita à mão ignora quais
+regiões estão presentes: `border-b` num cabeçalho sozinho desenha uma linha encostada na borda do
+card, e `border-t` no corpo duplica a linha que o cabeçalho já desenha. Da mesma forma,
+`border-b-0` não apaga a linha derivada. Para um card sem divisores, use `layout="continuous"`.
+
+## Mídia e ações no cabeçalho
+
+`CardMedia` abre a linha com a moldura de ícone do Opus — o mesmo [`IconTile`](/ui/icon-tile), na
+escala `sm`, com `context` e `variant` para declarar o significado da cor. `CardAction` fica no
+extremo oposto ao título, sem precisar de classe de alinhamento.
+
+```tsx preview col
+<Card layout="sectioned">
+  <CardHeader>
+    <CardMedia context="primary">
+      <CarFront />
+    </CardMedia>
+    <CardTitle>Revisão dos 20.000 km</CardTitle>
+    <CardDescription>Agendada para 12 de maio, às 9h.</CardDescription>
+    <CardAction>
+      <Button size="sm" variant="outline">Reagendar</Button>
+    </CardAction>
   </CardHeader>
   <CardBody>
-    <p className="text-sm text-muted-foreground">Vinculada a 4 agentes neste workspace.</p>
+    <p className="text-sm text-muted-foreground">Consultor responsável: Marina Alves.</p>
   </CardBody>
-  <CardFooter className="justify-between border-t">
-    <Badge context="success">Publicada</Badge>
-    <Button size="sm" variant="outline">Editar skill</Button>
-  </CardFooter>
 </Card>
 ```
 
-## Ação no cabeçalho
+## Hierarquia do título
 
-`CardAction` é o slot de ação do header (um botão ou menu). Quem compõe posiciona — em geral um
-`CardHeader` em `flex-row` com o título de um lado e a ação do outro.
+`CardTitle` é um heading. `level` escolhe a hierarquia do documento, de `1` a `6`, com `3` como
+padrão — um card costuma ser uma seção dentro de uma página que já tem o `h1`. O tamanho visual não
+vem daí: ele é decidido pela família e pelo `layout`, então corrigir o nível para acertar a
+estrutura do documento não muda a aparência.
 
 ```tsx preview col
 <Card>
-  <CardHeader className="flex-row items-start justify-between">
-    <div>
-      <CardTitle>Empresa X</CardTitle>
-      <CardDescription>3 agentes vinculados.</CardDescription>
-    </div>
-    <CardAction>
-      <Button size="sm" variant="outline">Editar</Button>
-    </CardAction>
+  <CardHeader>
+    <CardTitle level={2}>Qualidade da base</CardTitle>
+    <CardDescription>O nível muda a semântica; a escala continua a do layout.</CardDescription>
+  </CardHeader>
+</Card>
+```
+
+Quando o título leva a outra tela, coloque o link dentro dele. O heading continua sendo o
+`CardTitle`, e o link fica no seu conteúdo:
+
+```tsx preview col
+<Card>
+  <CardHeader>
+    <CardTitle>
+      <a href="#" className="hover:underline">Revisão dos 20.000 km</a>
+    </CardTitle>
+    <CardDescription>Agendada para 12 de maio, às 9h.</CardDescription>
   </CardHeader>
 </Card>
 ```
 
+Use `asChild` só quando outro componente já renderiza o próprio heading e precisa receber a escala do
+título. Com `asChild`, o elemento é o filho: `level` deixa de valer, e um link passado ali substitui
+o heading em vez de ficar dentro dele.
+
+## A matriz de slots
+
+As regiões são independentes: o cabeçalho existe sem corpo, o corpo existe sem cabeçalho e o rodapé
+entra apenas quando há ações persistentes. Os divisores acompanham as regiões presentes, e o corpo
+reassume o respiro de cima ou de baixo quando é a primeira ou a última região. No layout contínuo, o
+cabeçalho só se aproxima da região seguinte quando ela existe: sozinho, ele fecha o card com o mesmo
+respiro que tem em cima.
+
+```tsx preview col
+render(
+  <div className="grid grid-cols-2 gap-4">
+    <Card>
+      <CardHeader>
+        <CardMedia>
+          <UserRound />
+        </CardMedia>
+        <CardTitle>Contínuo com mídia</CardTitle>
+      </CardHeader>
+      <CardBody>
+        <p className="text-sm text-muted-foreground">
+          Sem rodapé, o corpo reassume o respiro de baixo.
+        </p>
+      </CardBody>
+    </Card>
+    <Card>
+      <CardBody>
+        <p className="text-sm text-muted-foreground">
+          Só corpo: o card vira uma caixa com o recuo da família.
+        </p>
+      </CardBody>
+    </Card>
+    <Card layout="sectioned">
+      <CardHeader>
+        <CardTitle>Seccionado sem corpo</CardTitle>
+        <CardAction>
+          <Button size="sm" variant="ghost">Editar</Button>
+        </CardAction>
+      </CardHeader>
+      <CardFooter>
+        <Button size="sm">Salvar</Button>
+      </CardFooter>
+    </Card>
+    <Card layout="sectioned">
+      <CardHeader>
+        <CardMedia context="success">
+          <ShieldCheck />
+        </CardMedia>
+        <CardTitle>Seccionado completo</CardTitle>
+        <CardDescription>Cabeçalho, corpo e rodapé.</CardDescription>
+      </CardHeader>
+      <CardBody>
+        <p className="text-sm text-muted-foreground">Cada fronteira ganha uma linha.</p>
+      </CardBody>
+      <CardFooter>
+        <Button size="sm" variant="outline">Descartar</Button>
+        <Button size="sm">Publicar</Button>
+      </CardFooter>
+    </Card>
+  </div>,
+);
+```
+
+No layout contínuo, o respiro de baixo de um cabeçalho sem corpo nem rodapé segue o de cima. Essa
+regra só vale quando o cabeçalho é a última região e tem precedência sobre o `className`, então um
+`pb-*` no `CardHeader` não altera esse recuo. Para um recuo diferente, escolha o `layout`: no
+`sectioned`, as regiões usam o recuo simétrico e mais contido das superfícies de operação.
+
 ## Propriedades de Card
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `asChild` | `boolean` | `false` | Renderiza o filho com a superfície do Card (ex.: um `<button>` clicável inteiro). |
-| `className` | `string` | | Compõe sobre a superfície; os slots (`CardHeader`, `CardBody`, `CardFooter`, `CardAction`) são donos do próprio padding. `CardContent` é alias depreciado de `CardBody`. |
+| `layout` | `'continuous' \| 'sectioned'` | `'continuous'` | Anatomia da superfície inteira; os slots leem esse valor e não o recebem. |
+| `asChild` | `boolean` | `false` | Renderiza o filho com a superfície do Card, por exemplo um `<button>` clicável inteiro. |
+| `className` | `string` | | Compõe sobre a superfície. Sem slots, é aqui que entra o recuo da caixa. |
+
+As demais propriedades são as propriedades nativas de `div`.
+
+## Propriedades de CardHeader
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Somente `CardMedia`, `CardTitle`, `CardDescription` e `CardAction`, no máximo um de cada. |
+| `className` | `string` | | Ajusta a faixa superior sobre o recuo do layout. |
+
+## Propriedades de CardMedia
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `size` | `'xs' \| 'sm' \| 'default' \| 'lg'` | `'sm'` | Tamanho da moldura e do glifo na escala compartilhada dos controles. |
+| `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Declara o significado da cor. |
+| `variant` | `'subtle' \| 'outline'` | `'subtle'` | Usa preenchimento tonal ou acrescenta borda. |
+| `className` | `string` | | Ajusta a moldura sem substituir a escala. |
+| `asChild` | `boolean` | `false` | Cede o elemento para uma marca com visual próprio — um orbe, um logotipo — que ocupa o slot sem ganhar a moldura por cima. |
+
+## Propriedades de CardTitle
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `3` | Hierarquia do documento. O tamanho vem do `layout`, nunca do nível. |
+| `asChild` | `boolean` | `false` | Usa o filho como elemento do título, com a escala do layout. Reserve para um componente que já renderiza um heading; com `asChild`, `level` não se aplica. |
+| `className` | `string` | | Ajusta o título. |
+
+## Propriedades de CardDescription
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Frase de apoio sob o título, dentro do cabeçalho. |
+| `className` | `string` | | Ajusta a descrição. |
+
+## Propriedades de CardAction
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Controles no extremo oposto ao título, como um botão ou um menu. |
+| `className` | `string` | | Ajusta o agrupamento das ações. |
+
+## Propriedades de CardBody
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Conteúdo principal do card. |
+| `className` | `string` | | Ajusta a região sobre o recuo do layout. |
+
+`CardContent` continua exportado como alias depreciado de `CardBody` e sai em uma próxima versão
+maior. Código novo usa `CardBody`.
+
+## Propriedades de CardFooter
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `ReactNode` | | Ações persistentes, alinhadas no fim da linha. |
+| `className` | `string` | | Ajusta o rodapé, inclusive a distribuição das ações. |

package/src/ui/docs/content/carousel.md

@@ -1,9 +1,16 @@
 ## Um slide por vez
 
-Compõe Carousel>CarouselContent>CarouselItem, com CarouselPrevious/CarouselNext para navegar. As setas ficam fora do trilho (-left-12/-right-12), então reserve a margem lateral no entorno.
+Use `Carousel` para percorrer uma sequência de itens do mesmo tipo em um espaço limitado, um ou
+alguns de cada vez. Para consultar e comparar muitos itens, prefira uma lista, como
+[`ActionList`](/ui/action-list), que mostra tudo de uma vez.
+
+Componha `Carousel` > `CarouselContent` > `CarouselItem` e acrescente `CarouselPrevious` e
+`CarouselNext` para navegar. As setas ficam `3rem` fora da área dos slides, então reserve essa
+margem lateral no entorno, como o `mx-12` do exemplo. Dê um nome ao carrossel com `aria-label`:
+ele é anunciado como uma região.
 
 ```tsx preview
-<Carousel className="mx-12 w-full max-w-xs">
+<Carousel className="mx-12 w-full max-w-xs" aria-label="Sessões recentes">
   <CarouselContent>
     <CarouselItem>
       <div className="flex h-32 items-center justify-center rounded-lg border bg-card text-sm">
@@ -28,10 +35,11 @@ Compõe Carousel>CarouselContent>CarouselItem, com CarouselPrevious/CarouselNext
 
 ## Vários por vista
 
-O basis do CarouselItem decide quantos cabem na vista — basis-1/3 mostra três slides por vez. Bom para galeria de workspaces ou repositórios.
+A largura de cada `CarouselItem` decide quantos slides cabem na área visível: `basis-1/3` mostra
+três por vez. `opts={{ align: 'start' }}` alinha o primeiro slide à borda inicial.
 
 ```tsx preview
-<Carousel className="mx-12 w-full max-w-sm" opts={{ align: 'start' }}>
+<Carousel className="mx-12 w-full max-w-sm" opts={{ align: 'start' }} aria-label="Sessões da semana">
   <CarouselContent>
     {['Sessão #128', 'Sessão #131', 'Sessão #134', 'Sessão #137', 'Sessão #140'].map((session) => (
       <CarouselItem key={session} className="basis-1/3">
@@ -48,10 +56,11 @@ O basis do CarouselItem decide quantos cabem na vista — basis-1/3 mostra três
 
 ## Vertical
 
-orientation=vertical empilha os slides; as setas migram para cima e para baixo (-top-12/-bottom-12). Dê uma altura ao CarouselContent para delimitar a vista.
+`orientation="vertical"` empilha os slides, e as setas passam para cima e para baixo, também
+`3rem` fora da área dos slides. Dê uma altura ao `CarouselContent` para delimitar a área visível.
 
 ```tsx preview
-<Carousel className="w-full max-w-xs" orientation="vertical">
+<Carousel className="my-12 w-full max-w-xs" orientation="vertical" aria-label="Agentes">
   <CarouselContent className="h-48">
     <CarouselItem>
       <div className="flex h-24 items-center justify-center rounded-lg border bg-card text-sm">
@@ -74,6 +83,20 @@ orientation=vertical empilha os slides; as setas migram para cima e para baixo (
 </Carousel>
 ```
 
+## Teclado
+
+Com o foco dentro do carrossel, as setas do teclado mostram o slide anterior e o próximo. Na
+orientação horizontal, use as setas esquerda e direita; na vertical, as setas para cima e para
+baixo. Os botões de navegação ficam desabilitados nas pontas, a menos que `opts` declare
+`{ loop: true }`.
+
+Em um campo editável dentro de um slide, como `input`, `textarea`, `select` ou um elemento
+`contenteditable`, as setas continuam movendo o cursor ou mudando a opção, sem trocar de slide. O
+mesmo vale para controles que navegam pelas setas, como [`Slider`](/ui/slider),
+[`RadioGroup`](/ui/radio-group), [`Tabs`](/ui/tabs), [`Toggle`](/ui/toggle) em grupo,
+[`Accordion`](/ui/accordion), listas e menus. Um carrossel colocado dentro de uma barra de
+ferramentas ou de uma grade continua respondendo às setas.
+
 ## Propriedades de Carousel
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -83,6 +106,14 @@ orientation=vertical empilha os slides; as setas migram para cima e para baixo (
 | `setApi` | `(api: EmblaCarouselType \| undefined) => void` | | Recebe a instância do Embla para controle externo, como navegar com `scrollTo` ou ler o slide ativo. |
 | `plugins` | `EmblaPluginType[]` | | Plugins do Embla associados ao carrossel, como autoplay. |
 
+Os demais atributos, como `aria-label` e `className`, vão para o elemento raiz.
+
+## Propriedades de CarouselContent
+
+`CarouselContent` delimita a área visível e recorta o que passa dela. Não tem props próprias;
+`className` e os demais atributos de `div` vão para a faixa interna que se desloca e contém os
+slides. Na orientação vertical, é nela que entra a altura, como `h-48`.
+
 ## Propriedades de CarouselItem
 
 | Propriedade | Tipo | Padrão | Descrição |