@softize/opus 18.4.0 → 18.5.0

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/registry.tsx

@@ -68,6 +68,7 @@ import chatMd from "./content/chat.md?raw";
 import checkboxMd from "./content/checkbox.md?raw";
 import collapsibleMd from "./content/collapsible.md?raw";
 import iconPickerMd from "./content/icon-picker.md?raw";
+import iconTileMd from "./content/icon-tile.md?raw";
 import commandMd from "./content/command.md?raw";
 import composerMd from "./content/composer.md?raw";
 import copyableMd from "./content/copyable.md?raw";
@@ -697,6 +698,11 @@ export const UI_SECTIONS: DocSection[] = [
             title: "Empty Value",
             render: comp("Empty Value", "empty-value", emptyValueMd),
           },
+          {
+            slug: "icon-tile",
+            title: "Icon Tile",
+            render: comp("Icon Tile", "icon-tile", iconTileMd),
+          },
           { slug: "item", title: "Item", render: comp("Item", "item", itemMd) },
           { slug: "kbd", title: "Kbd", render: comp("Kbd", "kbd", kbdMd) },
           {

package/src/ui/meta.ts

@@ -53,6 +53,12 @@ export const componentMeta = {
     whenToUse:
       "Sinal compacto de estado. `context` declara neutral/primary/info/success/warning/danger e `variant` escolhe solid/outline. Passe `label` quando a cor reforçar informação; sem label, o ponto é decorativo. Para texto visível, use Badge.",
   },
+  "icon-tile": {
+    name: "icon-tile",
+    ancestry: "opus",
+    whenToUse:
+      "Dê suporte visual não interativo a um ícone com tamanho, contexto, preenchimento e arredondamento consistentes. Componha-o nos slots que pedem a moldura; passe o ícone diretamente quando ela não for necessária. Para uma ação, use Button com tamanho de ícone.",
+  },
   detail: {
     name: "detail",
     ancestry: "opus",
@@ -117,7 +123,7 @@ export const componentMeta = {
     name: "content-header",
     ancestry: "opus",
     whenToUse:
-      "Estruture uma região de conteúdo com título, contador, descrição e ações. No caso comum, declare esses valores diretamente em Content; componha ContentHeader apenas quando precisar controlar a anatomia. Em coleções, Content mantém título e criação junto do ActionList. Contadores pertencem a Content e não ao título da Page.",
+      'Estruture uma região com título e corpo. No caso comum, declare título, descrição, contador e ações diretamente em Content; use `framed` quando a região precisar de limite próprio, `as="fieldset"` para agrupar campos sob uma legenda nativa e `frameVariant="legend"` somente quando essa legenda precisar integrar visualmente a borda. Componha ContentHeader apenas quando precisar controlar a anatomia.',
   },
   copyable: {
     name: "copyable",
@@ -279,7 +285,7 @@ export const componentMeta = {
     name: "field",
     ancestry: "shadcn",
     whenToUse:
-      "Componha rótulo, controle, ajuda e erro com espaçamento consistente. Use a orientação vertical no caso comum e a horizontal quando controle e texto precisarem ficar lado a lado; `responsive` continua aceito como alias da horizontal. Field cuida do layout; o formulário continua responsável por estado e validação.",
+      'Componha rótulo, controle, ajuda e erro com espaçamento consistente. Use a orientação vertical no caso comum e a horizontal quando controle e texto precisarem ficar lado a lado. FieldGroup organiza vários campos; quando o conjunto precisar de título, componha-o dentro de Content com `as="fieldset"`.',
   },
   "input-otp": {
     name: "input-otp",
@@ -382,7 +388,7 @@ export const componentMeta = {
     name: "action-list",
     ancestry: "opus",
     whenToUse:
-      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período e busca; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. Em uma página, envolva a lista com Content para manter título e criação junto da coleção. Para um único recurso, use ActionView.",
+      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período e busca; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. A tabela derivada não cria moldura própria. Em uma página, envolva a lista com Content para manter título e criação junto da coleção. Para um único recurso, use ActionView.",
   },
   "action-trigger": {
     name: "action-trigger",

package/src/ui/react.tsx

@@ -298,6 +298,21 @@ export {
   FieldSet,
   FieldTitle,
 } from "./components/primitives/field.tsx";
+export type {
+  FieldSetProps,
+  FieldSetVariant,
+} from "./components/primitives/field.tsx";
+export {
+  IconTile,
+  iconTileVariants,
+  resolveIconTileStyle,
+} from "./components/primitives/icon-tile.tsx";
+export type {
+  IconTileContext,
+  IconTileProps,
+  IconTileSize,
+  IconTileVariant,
+} from "./components/primitives/icon-tile.tsx";
 export {
   InputGroup,
   InputGroupAddon,
@@ -471,6 +486,8 @@ export {
 export type {
   ContentProps,
   ContentHeaderProps,
+  ContentElement,
+  ContentFrameVariant,
   ContentHeaderLevel,
   ContentHeaderVariant,
 } from "./components/patterns/content-header.tsx";