@softize/opus 18.4.0 → 19.0.0

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

@@ -1,8 +1,9 @@
 ## Painel lateral de detalhe
 
 Use `Drawer` para abrir detalhes ou edição junto a uma borda, preservando a referência visual da
-tela ao fundo. Para conteúdo curto e centralizado, prefira `Dialog`. Com `side="right"`, o painel
-entra pela direita e pode ser fechado por Esc, pelo overlay ou pelo botão de fechamento.
+tela ao fundo. Para conteúdo curto e centralizado, prefira [`Dialog`](/ui/dialog). Com
+`side="right"`, o painel entra pela direita e pode ser fechado por Esc, pelo overlay ou pelo botão
+de fechamento.
 
 ```tsx preview
 <Drawer>
@@ -23,11 +24,10 @@ entra pela direita e pode ser fechado por Esc, pelo overlay ou pelo botão de fe
 
 ## Edição com ações persistentes
 
-`side` aceita `top`, `right`, `bottom` e `left`. `DrawerFooter` mantém as ações no rodapé;
-`DrawerClose` fecha o painel sem exigir controle manual de estado. Como no `Dialog`, o cabeçalho
-recebe um divisor inferior e o rodapé usa um divisor superior. O corpo preserva o mesmo alinhamento
-horizontal entre título, conteúdo e ações. O fechamento do cabeçalho usa uma ação circular neutra
-e sutil; `closeSize` escolhe entre `xs` e `sm`, com `sm` como padrão.
+`side` aceita `top`, `right`, `bottom` e `left`. `DrawerFooter` mantém as ações no rodapé e
+`DrawerClose` fecha o painel sem exigir controle manual de estado. O corpo preserva o mesmo
+alinhamento horizontal do cabeçalho e do rodapé. O fechamento do cabeçalho usa uma ação circular
+neutra e sutil; `closeSize` escolhe entre `xs` e `sm`, com `sm` como padrão.
 
 ```tsx preview
 <Drawer>
@@ -54,6 +54,86 @@ e sutil; `closeSize` escolhe entre `xs` e `sm`, com `sm` como padrão.
 </Drawer>
 ```
 
+O rodapé usa a mesma faixa sutil do [`Dialog`](/ui/dialog). As duas famílias compartilham a
+anatomia, então um fluxo que começa em um modal e continua em um painel não muda de aparência no
+meio.
+
+## Regiões separadas ou contínuas
+
+`layout` declara a anatomia da superfície inteira e fica em `DrawerContent`; os slots leem esse
+valor e não o recebem. O padrão é `sectioned`: recuo igual nas três regiões, faixa no rodapé e
+divisor entre as regiões vizinhas. É o painel de trabalho, em que o corpo rola sob um cabeçalho e um
+rodapé fixos.
+
+Use `layout="continuous"` quando o painel apresentar um único bloco de leitura e a linha virar
+ruído.
+
+```tsx preview
+<Drawer>
+  <DrawerTrigger asChild>
+    <Button variant="outline">Ver resumo</Button>
+  </DrawerTrigger>
+  <DrawerContent layout="continuous">
+    <DrawerHeader>
+      <DrawerTitle>Resumo da execução</DrawerTitle>
+    </DrawerHeader>
+    <DrawerBody>
+      <p className="text-sm text-muted-foreground">
+        Concluída em 2 minutos, sem falhas registradas.
+      </p>
+    </DrawerBody>
+  </DrawerContent>
+</Drawer>
+```
+
+Os divisores do modo seccionado são derivados da vizinhança: cada região desenha a linha quando há
+uma região do outro lado. Um cabeçalho sem corpo não fecha nada, e um cabeçalho seguido direto de um
+rodapé produz uma linha só. A tela não escreve `border-b` nem `border-t`.
+
+## Mídia, ações e navegação no cabeçalho
+
+O cabeçalho reconhece quatro slots — `DrawerNavigation`, `DrawerMedia`, `DrawerTitle` e
+`DrawerActions` — e posiciona cada um: a navegação abre a linha, a mídia vem antes do título, o
+título ocupa a folga, as ações vão para o extremo oposto e o botão de fechar entra depois delas. Um
+nó que não seja um desses slots interrompe a renderização com um erro; contexto e conteúdo
+pertencem ao `DrawerBody`.
+
+`DrawerMedia` é a moldura de ícone da casa — o mesmo [`IconTile`](/ui/icon-tile) —, útil para
+identificar o tipo do recurso aberto. `DrawerNavigation` carrega o retorno de um fluxo encadeado,
+em que o painel permanece aberto e troca de etapa.
+
+```tsx preview
+<Drawer>
+  <DrawerTrigger asChild>
+    <Button variant="outline">Abrir veículo</Button>
+  </DrawerTrigger>
+  <DrawerContent side="right">
+    <DrawerHeader>
+      <DrawerNavigation>
+        <Button variant="ghost" size="icon-sm" aria-label="Voltar para a lista">
+          <ArrowLeft />
+        </Button>
+      </DrawerNavigation>
+      <DrawerMedia context="primary">
+        <CarFront />
+      </DrawerMedia>
+      <DrawerTitle>ABC-1D23</DrawerTitle>
+      <DrawerActions>
+        <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
+          <Ellipsis />
+        </Button>
+      </DrawerActions>
+    </DrawerHeader>
+    <DrawerBody>
+      <p className="text-sm text-muted-foreground">Histórico de passagens na oficina.</p>
+    </DrawerBody>
+  </DrawerContent>
+</Drawer>
+```
+
+O cabeçalho não recebe descrição: o painel já nomeia o recurso, e o contexto que ajuda a decidir
+aparece no começo do corpo, como texto ou `Alert`.
+
 ## Propriedades de Drawer
 
 | Propriedade    | Tipo                      | Padrão | Descrição                                                          |
@@ -66,12 +146,59 @@ e sutil; `closeSize` escolhe entre `xs` e `sm`, com `sm` como padrão.
 | Propriedade       | Tipo                                     | Padrão    | Descrição                                                                                  |
 | ----------------- | ---------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |
 | `side`            | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | Borda de onde o painel aparece.                                                            |
-| `showCloseButton` | `boolean`                                | `true`    | Inclui a ação de fechamento no header. Desative quando o painel exigir uma ação explícita. |
+| `layout`          | `'continuous' \| 'sectioned'`            | `'sectioned'` | Anatomia da superfície inteira; os slots leem esse valor e não o recebem.              |
+| `showCloseButton` | `boolean`                                | `true`    | Inclui a ação de fechamento no cabeçalho. Desative quando o painel exigir uma ação explícita. |
 | `closeDisabled`   | `boolean`                                | `false`   | Mantém a ação visível e impede fechar enquanto o painel está bloqueado.                    |
-| `closeSize`       | `"xs" \| "sm"`                         | `"sm"`   | Define o tamanho da ação circular de fechar.                                               |
+| `closeSize`       | `"xs" \| "sm"`                           | `"sm"`    | Define o tamanho da ação circular de fechar.                                               |
+
+## Propriedades de DrawerHeader
+
+| Propriedade | Tipo        | Padrão | Descrição                                                                                  |
+| ----------- | ----------- | ------ | ------------------------------------------------------------------------------------------ |
+| `className` | `string`    |        | Ajusta a faixa superior sobre o recuo do layout.                                           |
+| `children`  | `ReactNode` |        | Somente `DrawerNavigation`, `DrawerMedia`, `DrawerTitle` e `DrawerActions`, no máximo um de cada; o fechamento padrão entra depois deles. |
+
+## Propriedades de DrawerMedia
+
+| Propriedade | Tipo                                                                     | Padrão      | Descrição                                                     |
+| ----------- | ------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------- |
+| `size`      | `'xs' \| 'sm' \| 'default' \| 'lg'`                                      | `'sm'`      | Tamanho da moldura e do glifo na escala compartilhada.        |
+| `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 DrawerNavigation
+
+| Propriedade | Tipo        | Padrão | Descrição                                             |
+| ----------- | ----------- | ------ | ----------------------------------------------------- |
+| `className` | `string`    |        | Ajusta a região introdutória da linha.                |
+| `children`  | `ReactNode` |        | Retorno de um fluxo encadeado, antes do título.       |
+
+## Propriedades de DrawerActions
+
+| Propriedade | Tipo        | Padrão | Descrição                                                |
+| ----------- | ----------- | ------ | -------------------------------------------------------- |
+| `className` | `string`    |        | Ajusta o agrupamento das ações.                          |
+| `children`  | `ReactNode` |        | Ações da tela no cabeçalho, antes do botão de fechar.    |
+
+## Propriedades de DrawerTitle
+
+| Propriedade | Tipo        | Padrão | Descrição                                                           |
+| ----------- | ----------- | ------ | ------------------------------------------------------------------- |
+| `level`     | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `h2` da primitiva | Hierarquia do documento. O tamanho vem do `layout`, nunca do nível. |
+| `className` | `string`    |        | Ajusta o título, que trunca quando não cabe na linha.               |
+| `children`  | `ReactNode` |        | Nome do recurso ou da tarefa; nomeia a superfície para leitores de tela. |
 
 ## Propriedades de DrawerBody
 
 `DrawerBody` aceita os atributos de `HTMLDivElement` e ocupa a região flexível e rolável entre
 `DrawerHeader` e `DrawerFooter`. O cabeçalho nomeia o painel; contexto relevante entra no começo
 do corpo como texto ou `Alert`.
+
+## Propriedades de DrawerFooter
+
+| Propriedade | Tipo        | Padrão | Descrição                                                              |
+| ----------- | ----------- | ------ | ---------------------------------------------------------------------- |
+| `className` | `string`    |        | Ajusta a faixa do rodapé, inclusive a distribuição das ações.          |
+| `children`  | `ReactNode` |        | Ações persistentes, normalmente dentro de um `ButtonGroup`.            |

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

@@ -25,7 +25,9 @@ vincula ao controle, ligue-o ao controle por `aria-labelledby` para manter o nom
 <Field orientation="horizontal">
   <FieldContent>
     <FieldTitle id="auto-review-title">Acionar o revisor no handoff</FieldTitle>
-    <FieldDescription>Ao abrir o handoff, o agente reviewer entra na sessão automaticamente.</FieldDescription>
+    <FieldDescription>
+      Ao abrir o handoff, o agente reviewer entra na sessão automaticamente.
+    </FieldDescription>
   </FieldContent>
   <Switch id="auto-review" aria-labelledby="auto-review-title" defaultChecked />
 </Field>
@@ -33,22 +35,23 @@ vincula ao controle, ligue-o ao controle por `aria-labelledby` para manter o nom
 
 ## Conjunto com legenda e erro
 
-`FieldSet` agrupa campos sob uma `FieldLegend`; `FieldGroup` define o espaçamento e
-`FieldSeparator` marca uma divisão. `FieldError` aparece somente quando existe mensagem de erro.
-Declare `data-invalid="true"` no `Field` para que o rótulo acompanhe o contexto de erro;
-`aria-invalid` marca apenas o controle. O `ActionForm` define os dois atributos sozinho.
-
-Quando vários conjuntos compartilham a mesma superfície, use `variant="section"` para separar cada
-grupo com uma linha leve. `icon` acrescenta uma referência visual antes do título sem transformar o
-conjunto em outro card; escolha um ícone que represente a dimensão do grupo, não uma ação.
+Use `Content as="fieldset"` para nomear um conjunto de campos relacionados. O título vira a legenda
+nativa, enquanto `FieldGroup` define o espaçamento e `FieldSeparator` marca uma divisão.
+`FieldError` aparece somente quando existe mensagem de erro. Declare `data-invalid="true"` no
+`Field` para que o rótulo acompanhe o contexto de erro; `aria-invalid` marca apenas o controle. O
+`ActionForm` define os dois atributos sozinho.
 
 ```tsx preview col md
-<FieldSet>
-  <FieldLegend>Novo agente</FieldLegend>
+<Content as="fieldset" title="Novo agente">
   <FieldGroup>
     <Field data-invalid="true">
       <FieldLabel htmlFor="agent-name">Nome</FieldLabel>
-      <Input id="agent-name" defaultValue="" aria-invalid placeholder="Ex.: developer" />
+      <Input
+        id="agent-name"
+        defaultValue=""
+        aria-invalid
+        placeholder="Ex.: developer"
+      />
       <FieldError>Informe um nome para o agente.</FieldError>
     </Field>
     <FieldSeparator />
@@ -57,38 +60,83 @@ conjunto em outro card; escolha um ícone que represente a dimensão do grupo, n
         <span>Prompt</span>
         <LabelHelp help="A síntese vira a primeira mensagem da sessão." />
       </FieldLabel>
-      <Textarea id="agent-prompt" rows={3} defaultValue="Veste o papel de developer no workspace Empresa X." />
+      <Textarea
+        id="agent-prompt"
+        rows={3}
+        defaultValue="Veste o papel de developer no workspace Empresa X."
+      />
+    </Field>
+  </FieldGroup>
+</Content>
+```
+
+## Conjunto com moldura
+
+Use a moldura para distinguir grupos vizinhos que continuem pertencendo ao mesmo formulário. O
+título permanece uma legenda semântica. A moldura é contínua por padrão; quando o agrupamento pedir
+o acabamento compacto com a legenda integrada à borda, declare `frameVariant="legend"`.
+
+```tsx preview col md
+<Content
+  as="fieldset"
+  framed
+  frameVariant="legend"
+  title={
+    <span className="flex items-center gap-2">
+      <IconTile size="xs">
+        <CarFront />
+      </IconTile>
+      Veículo
+    </span>
+  }
+>
+  <FieldGroup>
+    <Field>
+      <FieldLabel htmlFor="vehicle-plate">Placa</FieldLabel>
+      <Input id="vehicle-plate" defaultValue="GBR1A03" />
     </Field>
   </FieldGroup>
-</FieldSet>
+</Content>
 ```
 
+## Compatibilidade de FieldSet
+
+`FieldSet` e `FieldLegend` continuam disponíveis para composições existentes. Em código novo,
+prefira `Content as="fieldset"`: ele reúne legenda, corpo e moldura na mesma anatomia usada pelas
+demais regiões nomeadas. A migração pode ser gradual porque os controles e o `FieldGroup` não mudam.
+
+## Propriedades de FieldSet
+
+| Propriedade | Tipo                  | Padrão    | Descrição                                                                     |
+| ----------- | --------------------- | --------- | ----------------------------------------------------------------------------- |
+| `variant`   | `'plain' \| 'framed'` | `'plain'` | Mantém o conjunto aberto ou aplica a moldura com a legenda integrada à borda. |
+
 ## Propriedades de Field
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `orientation` | `'vertical' \| 'horizontal' \| 'responsive'` | `'vertical'` | Direção fixa do campo. `responsive` permanece como alias compatível de `horizontal`. |
-| `data-invalid` | `boolean \| 'true' \| 'false'` | | Com `true`, aplica o contexto de erro ao campo e ao rótulo. O `ActionForm` define o atributo sozinho. |
+| Propriedade    | Tipo                                         | Padrão       | Descrição                                                                                             |
+| -------------- | -------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
+| `orientation`  | `'vertical' \| 'horizontal' \| 'responsive'` | `'vertical'` | Direção fixa do campo. `responsive` permanece como alias compatível de `horizontal`.                  |
+| `data-invalid` | `boolean \| 'true' \| 'false'`               |              | Com `true`, aplica o contexto de erro ao campo e ao rótulo. O `ActionForm` define o atributo sozinho. |
 
 ## Propriedades de FieldLegend
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `variant` | `'legend' \| 'label' \| 'section'` | `'legend'` | Define o porte de título, de rótulo compacto ou de seção com divisor. |
-| `icon` | `ReactNode` | | Exibe um ícone decorativo antes da legenda. Na variante `section`, o ícone recebe um suporte tonal. |
+| Propriedade | Tipo                               | Padrão     | Descrição                                                                                  |
+| ----------- | ---------------------------------- | ---------- | ------------------------------------------------------------------------------------------ |
+| `variant`   | `'legend' \| 'label' \| 'section'` | `'legend'` | Define o porte de título, de rótulo compacto ou de seção com divisor.                      |
+| `icon`      | `ReactNode`                        |            | Exibe conteúdo decorativo antes da legenda; componha `IconTile` quando quiser uma moldura. |
 
 ## Propriedades de FieldError
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `errors` | `Array<{ message?: string } \| undefined>` | | Deduplica e apresenta uma lista de erros; sem conteúdo, o componente não renderiza. |
-| `children` | `ReactNode` | | Mensagem literal, com prioridade sobre `errors`. |
+| Propriedade | Tipo                                       | Padrão | Descrição                                                                           |
+| ----------- | ------------------------------------------ | ------ | ----------------------------------------------------------------------------------- |
+| `errors`    | `Array<{ message?: string } \| undefined>` |        | Deduplica e apresenta uma lista de erros; sem conteúdo, o componente não renderiza. |
+| `children`  | `ReactNode`                                |        | Mensagem literal, com prioridade sobre `errors`.                                    |
 
 ## Propriedades de FieldSeparator
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `children` | `ReactNode` | | Rótulo opcional no centro da divisão; sem conteúdo, exibe somente a linha. |
+| Propriedade | Tipo        | Padrão | Descrição                                                                  |
+| ----------- | ----------- | ------ | -------------------------------------------------------------------------- |
+| `children`  | `ReactNode` |        | Rótulo opcional no centro da divisão; sem conteúdo, exibe somente a linha. |
 
 `FieldSet`, `FieldGroup`, `FieldContent`, `FieldLabel`, `FieldTitle` e `FieldDescription` aceitam as
-props nativas dos respectivos elementos e não adicionam propriedades próprias.
+props nativas dos respectivos elementos. `FieldSet` mantém `variant` durante a compatibilidade.

package/src/ui/docs/content/icon-tile.md

@@ -0,0 +1,47 @@
+## Moldura decorativa para ícone
+
+Use `IconTile` quando um ícone precisar de uma pequena superfície para ganhar hierarquia em uma
+legenda, item ou resumo. O componente não é interativo; para uma ação, use `Button` com tamanho de
+ícone e um nome acessível.
+
+```tsx preview row
+<IconTile size="xs"><UserRound /></IconTile>
+<IconTile size="sm" variant="outline"><CarFront /></IconTile>
+<IconTile context="primary"><CalendarDays /></IconTile>
+```
+
+O tamanho controla a caixa e o glifo pela escala compartilhada dos controles. Um ícone que declara
+uma classe `size-*` preserva a própria medida.
+
+## Em uma legenda
+
+Slots de ícone não criam a moldura automaticamente. Componha `IconTile` somente quando ela fizer
+sentido para a superfície.
+
+```tsx preview col md
+<Content
+  as="fieldset"
+  framed
+  frameVariant="legend"
+  title={
+    <span className="flex items-center gap-2">
+      <IconTile size="xs">
+        <CarFront />
+      </IconTile>
+      Veículo
+    </span>
+  }
+>
+  <FieldGroup />
+</Content>
+```
+
+## Propriedades
+
+| Propriedade | Tipo                                                                     | Padrão      | Descrição                                                     |
+| ----------- | ------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------- |
+| `context`   | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Declara o significado da cor.                                 |
+| `size`      | `'xs' \| 'sm' \| 'default' \| 'lg'`                                      | `'default'` | Define o tamanho da caixa e do glifo na escala compartilhada. |
+| `variant`   | `'subtle' \| 'outline'`                                                  | `'subtle'`  | Usa preenchimento tonal ou acrescenta borda.                  |
+
+As demais propriedades são as propriedades nativas de `span`.

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

@@ -45,7 +45,9 @@ apresente dois cards independentes.
   labelAction={
     <Tooltip>
       <TooltipTrigger asChild>
-        <Button size="icon-xs" variant="ghost" aria-label="Sobre Agendados"><Info /></Button>
+        <Button size="icon-xs" variant="ghost" aria-label="Sobre Agendados">
+          <Info />
+        </Button>
       </TooltipTrigger>
       <TooltipContent>Eventos atualmente agendados.</TooltipContent>
     </Tooltip>
@@ -56,7 +58,9 @@ apresente dois cards independentes.
     labelAction: (
       <Tooltip>
         <TooltipTrigger asChild>
-          <Button size="icon-xs" variant="ghost" aria-label="Sobre o período"><Info /></Button>
+          <Button size="icon-xs" variant="ghost" aria-label="Sobre o período">
+            <Info />
+          </Button>
         </TooltipTrigger>
         <TooltipContent>Agendamentos registrados dentro do período.</TooltipContent>
       </Tooltip>
@@ -65,6 +69,38 @@ apresente dois cards independentes.
 />
 ```
 
+## Como filtro ou seleção
+
+Use a ativação controlada quando escolher uma métrica também precisar aplicar um recorte. O card
+expõe o estado por `aria-pressed` e preserva controles complementares, como o tooltip do rótulo,
+sem disparar a ativação.
+
+```tsx preview col
+const [metric, setMetric] = useState('scheduled')
+
+render(
+  <div className="grid grid-cols-2 gap-3">
+    <MetricCard
+      label="Agendados"
+      value="18"
+      active={metric === 'scheduled'}
+      activationLabel="Filtrar por Agendados"
+      onActivate={() => setMetric('scheduled')}
+    />
+    <MetricCard
+      label="Efetivados"
+      value="11"
+      active={metric === 'completed'}
+      activationLabel="Filtrar por Efetivados"
+      onActivate={() => setMetric('completed')}
+    />
+  </div>,
+)
+```
+
+`active`, `activationLabel` e `onActivate` formam uma capacidade única: informe as três propriedades
+para tornar o card ativável. O consumidor continua responsável pelo estado e pelo recorte aplicado.
+
 ## Carregamento
 
 `loading` preserva a geometria do card com placeholders e marca a superfície como ocupada para
@@ -76,22 +112,25 @@ tecnologias assistivas. O contêiner da coleção continua responsável pela men
 
 ## Propriedades de MetricCard
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `label` | `ReactNode` | | O nome da medida. |
-| `value` | `ReactNode` | | O valor já formatado pelo consumidor. |
-| `loading` | `boolean` | `false` | Substitui rótulo e valor por skeletons e marca `aria-busy`. |
-| `labelAction` | `ReactNode` | | Controle ao lado do rótulo, como uma explicação em tooltip. |
-| `description` | `ReactNode` | | Contexto que explica recorte, proporção ou significado do valor. |
-| `secondaryMetric` | `MetricCardSecondaryMetric` | | Medida complementar exibida como uma lâmina posterior sob o card principal. |
-| `icon` | `ReactNode` | | Ícone decorativo que identifica a natureza da medida. |
-| `context` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Contexto semântico do ícone; não altera a superfície do card. |
-| `action` | `ReactNode` | | Ação relacionada diretamente à medida. |
+| Propriedade       | Tipo                                                        | Padrão      | Descrição                                                                                          |
+| ----------------- | ----------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
+| `label`           | `ReactNode`                                                 |             | O nome da medida.                                                                                  |
+| `value`           | `ReactNode`                                                 |             | O valor já formatado pelo consumidor.                                                              |
+| `loading`         | `boolean`                                                   | `false`     | Substitui rótulo e valor por skeletons e marca `aria-busy`.                                        |
+| `labelAction`     | `ReactNode`                                                 |             | Controle ao lado do rótulo, como uma explicação em tooltip.                                        |
+| `description`     | `ReactNode`                                                 |             | Contexto que explica recorte, proporção ou significado do valor.                                   |
+| `secondaryMetric` | `MetricCardSecondaryMetric`                                 |             | Medida complementar exibida como uma lâmina posterior sob o card principal.                        |
+| `icon`            | `ReactNode`                                                 |             | Ícone decorativo que identifica a natureza da medida.                                              |
+| `context`         | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Contexto semântico do ícone; não altera a superfície do card.                                      |
+| `action`          | `ReactNode`                                                 |             | Ação relacionada diretamente à medida.                                                             |
+| `active`          | `boolean`                                                   |             | Indica se a medida controla o recorte atualmente aplicado. Exige `activationLabel` e `onActivate`. |
+| `activationLabel` | `string`                                                    |             | Nome acessível da ativação. Exige `active` e `onActivate`.                                         |
+| `onActivate`      | `() => void`                                                |             | Ativa a medida como recorte ou seleção. Exige `active` e `activationLabel`.                        |
 
 ## Propriedades de MetricCardSecondaryMetric
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `label` | `ReactNode` | | O nome da medida complementar. |
-| `value` | `ReactNode` | | O valor complementar já formatado pelo consumidor. |
-| `labelAction` | `ReactNode` | | Controle próprio ao lado do rótulo, como uma explicação em tooltip. |
+| Propriedade   | Tipo        | Padrão | Descrição                                                           |
+| ------------- | ----------- | ------ | ------------------------------------------------------------------- |
+| `label`       | `ReactNode` |        | O nome da medida complementar.                                      |
+| `value`       | `ReactNode` |        | O valor complementar já formatado pelo consumidor.                  |
+| `labelAction` | `ReactNode` |        | Controle próprio ao lado do rótulo, como uma explicação em tooltip. |

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

@@ -17,6 +17,13 @@ introdução podem ser omitidos quando o próprio conteúdo nomeia a página.
 Contadores e outros indicadores pertencem ao
 conteúdo que os explica.
 
+A `Page` é contínua por definição: separar o chrome do conteúdo é trabalho do shell, e não há
+divisores entre regiões para declarar. O `layout` da `Page` não é a anatomia de superfície de
+[`Card`](/ui/card), [`Dialog`](/ui/dialog), [`Drawer`](/ui/drawer) e [`Pane`](/ui/pane) — aqui ele
+decide a ocupação de altura. `flow`, o padrão, deixa a página crescer e a rolagem acontecer na
+janela; `fill` limita a página à altura do shell para que uma região interna, como uma tabela longa
+ou um split, assuma a rolagem.
+
 `PageShell` não inclui sidebar nem inventa breadcrumb. Ele ocupa o painel principal já delimitado e
 mantém a barra com `3.75rem`, mesmo quando o conteúdo muda de estado. Tabs ficam reservados a recortes
 da mesma superfície. Canvas e outros workspaces espaciais imersivos podem usar um shell próprio.
@@ -196,6 +203,7 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 | ----------- | ----------- | ----------- | ----------------------------------------------------------------------------------------------- |
 | `title`     | `ReactNode` |             | O h1 da página.                                                                                 |
 | `actions`   | `ReactNode` |             | Ações contextuais no extremo oposto do cabeçalho. |
+| `layout`    | `'flow' \| 'fill'` | `'flow'` | Ocupação de altura, não anatomia: `fill` limita a página ao shell para que uma região interna role. |
 | `className` | `string`    | `max-w-7xl` | Classes do container para substituir o teto padrão de `80rem`.                                  |
 | `children`  | `ReactNode` |             | O body da página — espaçamento e diagramação são seus.                                          |