@softize/opus 23.0.0 → 24.0.0

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

@@ -1,275 +0,0 @@
-## Região de conteúdo
-
-Use `Content` para dar título e estrutura a uma região dentro de `PageBody`, `CardBody`,
-`DialogBody` ou outra superfície. Ele renderiza uma `section` ligada ao próprio título e mantém o
-espaçamento entre header e body. `ContentHeader` pertence sempre a essa estrutura; não o use solto.
-
-O `Content` é uma região nomeada dentro de outra superfície. Sem moldura, ele mantém a anatomia
-contínua. Com `framed`, pode permanecer contínuo ou separar header e body com
-`layout="sectioned"`. O layout organiza as regiões internas; não transforma `Content` em
-[`Card`](/ui/card), [`Dialog`](/ui/dialog), [`Drawer`](/ui/drawer) ou [`Pane`](/ui/pane). Pelo mesmo
-motivo o `Content` não tem rodapé: um rodapé pertence à superfície que o hospeda.
-
-No caso comum, prefira o shorthand. `count` mostra o total de itens ao lado do título:
-
-```tsx preview col
-render(
-  <Content
-    title="Dispositivos conectados"
-    count={3}
-    description="Sessões com acesso à sua conta."
-    actions={<Button variant="outline">Encerrar outras sessões</Button>}
-  >
-    <div className="rounded-lg border border-border p-4">
-      MacBook Pro · ativo agora
-    </div>
-  </Content>,
-);
-```
-
-## Região com moldura
-
-Use `framed` quando título e corpo precisarem formar uma única região delimitada. A moldura pertence
-ao `Content`; componentes internos, como `DetailGroup`, continuam responsáveis somente pelo layout
-e pela semântica dos próprios dados. Por padrão, a borda permanece contínua e o header fica dentro
-do recuo da região.
-
-```tsx preview col
-render(
-  <Content framed title="Cliente" media={<UserRound aria-hidden="true" />}>
-    <DetailGroup columns={2}>
-      <DetailField label="Nome" value="Carla Souza" />
-      <DetailField label="Telefone" value="+55 11 97333-4455" />
-    </DetailGroup>
-  </Content>,
-);
-```
-
-## Header integrado à moldura
-
-Quando uma região compacta precisar integrar visualmente o header à borda, use
-`frameVariant="legend"`. O acabamento não muda a semântica: uma região de leitura continua sendo
-uma `section`, o título continua sendo um heading e descrição, contador e ações permanecem
-disponíveis.
-
-```tsx preview col
-render(
-  <Content
-    framed
-    frameVariant="legend"
-    title="Veículo"
-    media={<CarFront aria-hidden="true" />}
-  >
-    <DetailGroup columns={2}>
-      <DetailField label="Placa" value="ABC1D23" />
-      <DetailField label="Modelo" value="Corolla XEi" />
-    </DetailGroup>
-  </Content>,
-);
-```
-
-Para interromper a borda, o header pinta o título e as ações com o fundo da superfície que hospeda o
-`Content`, lido da variável CSS `--surface-background`. `Card`, `Dialog` e `Drawer` já a declaram
-com o fundo que pintam; fora deles, vale `--background`. Uma superfície com fundo próprio, como um
-`Card` com `bg-*`, um `Popover` ou um contêiner da aplicação, precisa declarar a variável com o
-mesmo fundo. Sem isso, a faixa atrás do título aparece com a cor da página.
-
-```tsx preview col
-render(
-  <Card className="bg-muted [--surface-background:var(--muted)]">
-    <CardBody>
-      <Content framed frameVariant="legend" title="Veículo">
-        <DetailGroup columns={2}>
-          <DetailField label="Placa" value="ABC1D23" />
-          <DetailField label="Modelo" value="Corolla XEi" />
-        </DetailGroup>
-      </Content>
-    </CardBody>
-  </Card>,
-);
-```
-
-## Header e body seccionados
-
-Use `layout="sectioned"` quando o filho do body já controlar o recuo de suas células, linhas ou
-itens. O header recebe `p-3` e divisor inferior; o body fica sem padding para que a estrutura interna
-alcance a moldura. Esse layout exige `framed`.
-
-```tsx preview col
-render(
-  <Content
-    framed
-    layout="sectioned"
-    title="Veículo"
-    media={<CarFront aria-hidden="true" />}
-  >
-    <DetailGroup dividers columns={2} orientation="horizontal">
-      <DetailField label="Marca" value="Toyota" />
-      <DetailField label="Modelo" value="Yaris XLS" />
-      <DetailField label="Ano/modelo" value="2021" />
-      <DetailField label="Placa" value="EVT0012" />
-    </DetailGroup>
-  </Content>,
-);
-```
-
-Conteúdo livre que não possui recuo próprio continua no layout `continuous`. Não combine
-`layout="sectioned"` com `frameVariant="legend"`: `sectioned` coloca o header dentro da moldura;
-`legend` integra o header ao traço externo.
-
-## Grupo de campos
-
-Quando a região nomear um conjunto de campos relacionados, use `as="fieldset"`. O `Content`
-renderiza o título como `legend`, preserva as props nativas do `fieldset` e mantém o mesmo contrato
-de título e corpo. Essa escolha altera somente a semântica e o comportamento nativo; com `framed`,
-a moldura permanece contínua. A mídia usa a mesma apresentação da `section`; contador, descrição e
-ações não entram na legenda.
-
-```tsx preview col
-render(
-  <Content
-    as="fieldset"
-    framed
-    title="Proprietário"
-    media={<UserRound aria-hidden="true" />}
-  >
-    <FieldGroup>
-      <Field>
-        <FieldLabel htmlFor="owner-name">Nome</FieldLabel>
-        <Input id="owner-name" />
-      </Field>
-      <Field>
-        <FieldLabel htmlFor="owner-document">CPF/CNPJ</FieldLabel>
-        <Input id="owner-document" />
-      </Field>
-    </FieldGroup>
-  </Content>,
-);
-```
-
-O mesmo acabamento pode integrar a legenda nativa à borda. Declare `frameVariant="legend"` em
-agrupamentos compactos, como as seções de filtros avançados; `as="fieldset"` continua sendo a
-decisão semântica, e não uma forma de obter esse desenho.
-
-```tsx preview col
-render(
-  <Content as="fieldset" framed frameVariant="legend" title="Dados do veículo">
-    <FieldGroup>
-      <Field>
-        <FieldLabel htmlFor="vehicle-plate">Placa</FieldLabel>
-        <Input id="vehicle-plate" />
-      </Field>
-    </FieldGroup>
-  </Content>,
-);
-```
-
-## Composição explícita
-
-Use os slots quando o header precisar de composição própria. A árvore aceita exatamente um
-`ContentHeader` e um `ContentBody` como filhos diretos. O header exige um `ContentTitle` e aceita
-uma mídia (`ContentMedia`), uma descrição, um contador (`ContentMeta`) e uma região de ações. O
-contador é próprio de `Content`; `PageHeader` reconhece somente navegação, título e ações.
-
-```tsx preview col
-render(
-  <Content level={2}>
-    <ContentHeader>
-      <ContentMedia>
-        <Monitor aria-hidden="true" />
-      </ContentMedia>
-      <ContentTitle>Dispositivos conectados</ContentTitle>
-      <ContentMeta>3</ContentMeta>
-      <ContentDescription>Sessões com acesso à sua conta.</ContentDescription>
-      <ContentActions>
-        <Button variant="outline">Atualizar</Button>
-      </ContentActions>
-    </ContentHeader>
-    <ContentBody>
-      <div className="rounded-lg border border-border p-4">
-        MacBook Pro · ativo agora
-      </div>
-    </ContentBody>
-  </Content>,
-);
-```
-
-As duas formas geram os mesmos elementos, estilos e `data-slot`. `opus check` reprova slots fora
-do pai correto, filhos estruturais indiretos e a mistura de shorthand com composição explícita.
-
-## Coleção nomeada
-
-Quando a região principal da página é uma coleção, `Content` nomeia e governa essa coleção, enquanto
-[`ActionList`](/ui/action-list) executa a consulta. Coloque criar, importar e outras ações sobre o conjunto completo em
-`ContentActions`. Busca, filtros, atualização e operações dependentes do recorte atual permanecem na
-toolbar da lista. Essa divisão aproxima cada comando do objeto que ele afeta sem criar uma família
-paralela de componentes `List*`.
-
-Quando a coleção é o assunto da página, use `level={1}`: o `Content` passa a ser o heading
-principal, assume automaticamente a escala do cabeçalho de [`Page`](/ui/page) e mantém o mesmo
-ritmo entre introdução e corpo. As ações ficam no extremo oposto ao título. Níveis de 2 a 6
-continuam usando a apresentação compacta de uma seção.
-
-```tsx preview col
-render(
-  <Content
-    level={1}
-    title="Clientes"
-    actions={<Button>Criar cliente</Button>}
-  >
-    <div className="rounded-lg border border-border p-4 text-sm text-muted-foreground">
-      A lista de clientes ocupa o corpo.
-    </div>
-  </Content>,
-);
-```
-
-A criação usa um `Button` textual na variante padrão (`solid`) e no tamanho `default`, sem ícone,
-nomeado `Criar {recurso}` (por exemplo, `Criar cliente`); o diálogo aberto pelo gatilho repete esse
-título, e a edição usa `Editar {recurso}`.
-
-Em uma [`Page`](/ui/page) com `layout="fill"`, a coleção pode ocupar a altura da página e rolar só os
-resultados. `Content` e `ContentBody` repassam a altura até a [`ActionList`](/ui/action-list) sem
-classes adicionais; um `Content` irmão, sem lista, mantém a altura do próprio conteúdo. A seção
-“Ocupar a altura disponível” da `ActionList` mostra a composição completa.
-
-## Propriedades de Content
-
-| Propriedade    | Tipo                          | Padrão         | Descrição                                                                                                         |
-| -------------- | ----------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `title`        | `ReactNode`                   |                | Forma curta: título da região (vira o heading ligado à `section`).                                                |
-| `media`        | `ReactNode`                   |                | Forma curta: ícone ou imagem que identifica a região antes do título.                                             |
-| `count`        | `number`                      |                | Forma curta: total de itens ao lado do título da região.                                                          |
-| `description`  | `ReactNode`                   |                | Forma curta: frase de apoio sob o título.                                                                         |
-| `actions`      | `ReactNode`                   |                | Forma curta: ações sobre a região inteira, no extremo oposto ao título.                                           |
-| `level`        | `1 \| 2 \| 3 \| 4 \| 5 \| 6`  | `2`            | Nível do heading; `1` identifica o conteúdo principal da página e os demais, uma seção interna.                   |
-| `as`           | `'section' \| 'fieldset'`     | `'section'`    | Usa uma região com heading ou um grupo de campos cujo título é a legenda nativa.                                  |
-| `framed`       | `boolean`                     | `false`        | Envolve o header e o body com a moldura estrutural da região.                                                     |
-| `layout`       | `'continuous' \| 'sectioned'` | `'continuous'` | Mantém header e body contínuos ou os separa com divisor e body sem recuo. `sectioned` exige `framed`.             |
-| `frameVariant` | `'default' \| 'legend'`       | `'default'`    | Mantém a borda contínua ou integra visualmente o header à moldura. `legend` não combina com `layout="sectioned"`. |
-| `children`     | `ReactNode`                   |                | Corpo da região na forma curta, ou `ContentHeader` e `ContentBody` na composição explícita.                       |
-
-As demais propriedades são as nativas de `section` ou, com `as="fieldset"`, de `fieldset`.
-
-Na composição explícita de uma `section`, `ContentHeader` recebe `ContentMedia`, `ContentTitle`,
-`ContentMeta`, `ContentDescription` e `ContentActions`. Em `fieldset`, recebe `ContentMedia` e
-`ContentTitle`, preservando a apresentação enquanto a legenda continua nomeando somente o grupo de
-campos. `ContentBody` recebe o conteúdo; nenhum desses slots aceita `title` ou `level` próprios — a
-hierarquia é declarada em `Content`. `ContentHeader` não existe fora de `Content`.
-
-## Propriedades de ContentMedia
-
-| Propriedade | Tipo                                                                     | Padrão      | Descrição                                                                                                                  |
-| ----------- | ------------------------------------------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `size`      | `'xs' \| 'sm' \| 'default' \| 'lg'`                                      | `'xs'`      | 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. |
-
-`ContentMedia` já é a moldura. Passe só o glifo e escolha `size`, `context` e `variant` no slot. Um
-`IconTile` passado em `media` ou dentro de `ContentMedia` não vira moldura dentro de moldura: o slot
-assume o lugar dele e herda o que ele declara. `media` com `null` ou `false` não desenha nada.
-
-Em `fieldset`, a mídia é sempre decorativa: o `Content` a esconde da árvore de acessibilidade para
-que o grupo seja anunciado apenas pelo título.