@softize/opus 18.4.0 → 18.5.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 18.5.0 — 2026-09-22
+
+`Content` passa a concentrar estrutura e apresentação de blocos com cabeçalho e corpo: aceita
+`as="section" | "fieldset"`, `variant="page" | "section"` e moldura opcional com
+`frameVariant="default" | "legend"`. O novo
+`IconTile` mantém a moldura do ícone como composição explícita, permitindo usar o mesmo ícone com
+ou sem esse apoio visual.
+
+`ActionList` deixa de aplicar moldura por padrão. No layout `fill`, mantém o cabeçalho fixo sobre a
+cor da superfície, com borda inferior durante a rolagem. Filtros avançados podem escolher o tratamento das seções sem
+recriar o fieldset no consumidor. Labels de campos e detalhes compartilham a mesma escala tipográfica.
+
 ## 18.4.0 — 2026-09-21
 
 `executions` acrescenta infraestrutura experimental de acompanhamento: snapshots versionados,

package/docs/adr/0020-icon-tiles-are-explicitly-composed.md

@@ -0,0 +1,46 @@
+# ADR 0020 — Molduras de ícone são compostas explicitamente
+
+- **Status:** aceita.
+- **Data:** 2026-09-18.
+
+## Contexto
+
+Várias interfaces apresentam um ícone dentro de uma pequena superfície quadrada. A mesma forma
+aparecia incorporada em componentes como `FieldLegend`, `ItemMedia` e `EmptyMedia`, ou era
+reconstruída pelo consumidor. Em `FieldLegend`, isso também vinculava a moldura à variante da
+legenda: o consumidor conseguia escolher o ícone, mas não se ele deveria receber a superfície.
+
+## Decisão
+
+`IconTile` passa a representar a moldura visual não interativa de um ícone. Ele compartilha a
+escala de tamanhos dos controles, declara a cor por `context` e oferece os tratamentos `subtle` e
+`outline`.
+
+Slots que aceitam conteúdo, como `FieldLegend.icon`, continuam genéricos. O consumidor passa um
+ícone diretamente quando quer somente o glifo ou compõe `<IconTile><Icon /></IconTile>` quando a
+moldura reforça a hierarquia. `ItemMedia variant="icon"` e `EmptyMedia variant="icon"` reutilizam
+a mesma base visual porque essas variantes já prometem a moldura.
+
+`IconTile` é somente apresentação. Quando o ícone aciona algo, deve-se usar `Button` com tamanho
+de ícone e nome acessível.
+
+## Consequências
+
+- A presença da moldura deixa de ser uma regra implícita da legenda.
+- Tamanho, arredondamento e preenchimento convergem entre consumidores.
+- Um slot permanece flexível sem acumular propriedades como `iconFramed` ou `iconTile`.
+- Migrações devem distinguir molduras decorativas de botões e indicadores semânticos.
+
+## Alternativas descartadas
+
+- **Adicionar uma propriedade à `FieldLegend`:** resolveria apenas uma superfície e ampliaria o
+  contrato toda vez que outra composição precisasse escolher a moldura.
+- **Manter classes livres em cada consumidor:** preservaria divergências de escala e acabamento.
+- **Usar `Button` desabilitado:** comunicaria interatividade onde não existe ação.
+
+## Verificação
+
+- teste estrutural cobre tamanho, variante e tamanho do glifo de `IconTile`;
+- teste de `FieldLegend` confirma que o slot não adiciona moldura por conta própria;
+- teste da API pública garante que o componente e seus metadados sejam exportados;
+- documentação de `Field` mostra a composição explícita.

package/docs/adr/0021-content-carries-structure-and-semantic-element.md

@@ -0,0 +1,65 @@
+# ADR 0021 — Content reúne estrutura visual e elemento semântico
+
+- **Status:** aceita.
+- **Data:** 2026-09-19.
+
+## Contexto
+
+Regiões com título e corpo usam `Content`, mas grupos de formulário precisam reconstruir a mesma
+estrutura com `FieldSet` e `FieldLegend`. Molduras aplicadas diretamente em `DetailGroup` também
+separam visualmente o título dos dados que ele nomeia. Essa sobreposição aumenta a quantidade de
+estruturas que a documentação e os consumidores precisam combinar.
+
+## Decisão
+
+`Content` continua responsável pela anatomia `Header + Body` e passa a aceitar:
+
+- `framed`, que aplica a moldura à região inteira;
+- `as="fieldset"`, que renderiza a raiz como `fieldset` e o título como `legend`.
+- `frameVariant="legend"`, que integra visualmente a legenda à borda quando esse acabamento for
+  escolhido de forma explícita.
+
+O default permanece `as="section"` sem moldura. `FieldGroup` organiza campos dentro do corpo e
+`DetailGroup` preserva a semântica de lista de definições sem assumir a moldura da região.
+`FieldSet` permanece disponível para compatibilidade e para composições que não precisam da
+anatomia completa de `Content`.
+
+No modo `fieldset`, a legenda aceita somente o título. Contador, descrição e ações não são filhos
+válidos de `legend`; consumidores que precisarem dessas regiões devem mantê-las no corpo ou usar
+uma `section`. A escolha de `fieldset` não define o acabamento visual: quando `framed` estiver
+presente, a moldura é contínua por padrão. Os filtros avançados preservam a legenda integrada à
+borda declarando `frameVariant="legend"`.
+
+## Consequências
+
+- A mesma API nomeia e delimita regiões de leitura e grupos de formulário.
+- A escolha do elemento semântico não fica acoplada à presença da moldura.
+- O recorte visual da borda deixa de ser consequência implícita do elemento semântico.
+- A forma curta continua sendo o caminho comum, enquanto a composição explícita permanece
+  disponível nos dois elementos.
+- A migração de `FieldSet` pode ser gradual e não exige remoção nesta versão.
+
+## Alternativas consideradas
+
+### Criar Panel
+
+Separaria a moldura de `Content`, mas criaria outra raiz com header e body para documentar e
+compor. Foi descartada porque `Content` já possui essa responsabilidade.
+
+### Renomear FieldSet para FieldGroup
+
+Produziria simetria nominal com `DetailGroup`, mas perderia a distinção entre a fronteira semântica
+do formulário e o layout interno dos campos. Foi descartada porque `FieldGroup` já representa esse
+layout.
+
+### Adicionar um booleano fieldset
+
+Permitiria alternar o elemento, mas trataria semântica como estado visual. Foi descartada em favor
+de `as`, que explicita o elemento renderizado.
+
+## Verificação
+
+- Testes de UI confirmam `section` e heading como defaults.
+- Testes de UI confirmam `fieldset`, `legend`, props nativas e ausência de heading nesse modo.
+- Testes reprovam slots incompatíveis com a legenda.
+- A documentação demonstra `Content + DetailGroup` e `Content as="fieldset" + FieldGroup`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "18.4.0",
+  "version": "18.5.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/src/ui/components/patterns/content-header.tsx

@@ -4,6 +4,7 @@ import {
   isValidElement,
   useContext,
   useId,
+  type ComponentProps,
   type HTMLAttributes,
   type ReactElement,
   type ReactNode,
@@ -18,8 +19,13 @@ import {
 
 export type ContentHeaderLevel = 1 | 2 | 3 | 4 | 5 | 6;
 export type ContentHeaderVariant = SurfaceHeaderVariant;
+export type ContentElement = "section" | "fieldset";
+export type ContentFrameVariant = "default" | "legend";
 
 interface ContentContextValue {
+  element: ContentElement;
+  frameVariant: ContentFrameVariant;
+  framed: boolean;
   level: ContentHeaderLevel;
   titleId: string;
   variant: ContentHeaderVariant;
@@ -38,17 +44,37 @@ function requiredContext<T>(
   return value;
 }
 
-interface ContentBaseProps extends Omit<
-  HTMLAttributes<HTMLElement>,
-  "children" | "title"
-> {
-  /** Nível semântico do heading, independente de seu destaque visual. */
-  level?: ContentHeaderLevel;
+interface ContentSharedProps {
+  /** Aplica a moldura estrutural da região sem transferi-la ao conteúdo interno. */
+  framed?: boolean;
   /** Hierarquia visual: `section` (default) ou `page`, a mesma de PageHeader. */
   variant?: ContentHeaderVariant;
 }
 
-interface ContentShorthandProps extends ContentBaseProps {
+interface ContentSectionBaseProps
+  extends
+    ContentSharedProps,
+    Omit<ComponentProps<"section">, "children" | "title"> {
+  /** Elemento semântico da região. */
+  as?: "section";
+  frameVariant?: "default";
+  /** Nível semântico do heading, independente de seu destaque visual. */
+  level?: ContentHeaderLevel;
+}
+
+interface ContentFieldsetBaseProps
+  extends
+    ContentSharedProps,
+    Omit<ComponentProps<"fieldset">, "children" | "title"> {
+  /** Usa a semântica nativa de grupo de campos; o título vira `legend`. */
+  as: "fieldset";
+  /** Tratamento visual da moldura: contínua (default) ou recortada pela legenda. */
+  frameVariant?: ContentFrameVariant;
+  level?: never;
+  variant?: "section";
+}
+
+interface ContentSectionShorthandProps extends ContentSectionBaseProps {
   title: ReactNode;
   /** Total de itens ao lado do título da seção. A página não carrega contador (ADR 0009). */
   count?: number;
@@ -57,7 +83,15 @@ interface ContentShorthandProps extends ContentBaseProps {
   children: ReactNode;
 }
 
-interface ContentComposedProps extends ContentBaseProps {
+interface ContentFieldsetShorthandProps extends ContentFieldsetBaseProps {
+  title: ReactNode;
+  count?: never;
+  description?: never;
+  actions?: never;
+  children: ReactNode;
+}
+
+interface ContentComposedProps {
   title?: never;
   count?: never;
   description?: never;
@@ -65,22 +99,36 @@ interface ContentComposedProps extends ContentBaseProps {
   children: ReactNode;
 }
 
-export type ContentProps = ContentShorthandProps | ContentComposedProps;
+export type ContentProps =
+  | ContentSectionShorthandProps
+  | ContentFieldsetShorthandProps
+  | ((ContentSectionBaseProps | ContentFieldsetBaseProps) &
+      ContentComposedProps);
 
 /** Região de conteúdo nomeada. A forma curta e a explícita produzem a mesma anatomia. */
 export function Content({
+  as = "section",
   title,
   count,
   description,
   actions,
   level = 2,
   variant = "section",
+  framed = false,
+  frameVariant = "default",
   children,
   className,
   ...props
 }: ContentProps): ReactElement {
   const titleId = useId();
-  const context = { level, titleId, variant };
+  const context = {
+    element: as,
+    frameVariant,
+    framed,
+    level: level as ContentHeaderLevel,
+    titleId,
+    variant,
+  };
   const shorthand = title !== undefined;
   const nodes = Children.toArray(children);
 
@@ -110,34 +158,64 @@ export function Content({
     }
   }
 
+  const anatomy = shorthand ? (
+    <>
+      <ContentHeader>
+        <ContentTitle>{title}</ContentTitle>
+        {count !== undefined && <ContentMeta>{count}</ContentMeta>}
+        {description !== undefined && (
+          <ContentDescription>{description}</ContentDescription>
+        )}
+        {actions !== undefined && <ContentActions>{actions}</ContentActions>}
+      </ContentHeader>
+      <ContentBody>{children}</ContentBody>
+    </>
+  ) : (
+    children
+  );
+  const ariaLabelledBy =
+    props["aria-label"] === undefined ? titleId : undefined;
+
   return (
     <ContentContext.Provider value={context}>
-      <section
-        data-slot="content"
-        aria-labelledby={
-          props["aria-label"] === undefined ? titleId : undefined
-        }
-        className={cn("space-y-3", className)}
-        {...props}
-      >
-        {shorthand ? (
-          <>
-            <ContentHeader>
-              <ContentTitle>{title}</ContentTitle>
-              {count !== undefined && <ContentMeta>{count}</ContentMeta>}
-              {description !== undefined && (
-                <ContentDescription>{description}</ContentDescription>
-              )}
-              {actions !== undefined && (
-                <ContentActions>{actions}</ContentActions>
-              )}
-            </ContentHeader>
-            <ContentBody>{children}</ContentBody>
-          </>
-        ) : (
-          children
-        )}
-      </section>
+      {as === "fieldset" ? (
+        <fieldset
+          data-slot="content"
+          data-as="fieldset"
+          data-framed={framed}
+          data-frame-variant={frameVariant}
+          aria-labelledby={ariaLabelledBy}
+          className={cn(
+            !framed && "space-y-3",
+            framed &&
+              frameVariant === "default" &&
+              "rounded-lg border border-border p-4",
+            framed &&
+              frameVariant === "legend" &&
+              "space-y-3 rounded-lg border border-border px-4 pb-4",
+            className,
+          )}
+          {...(props as ComponentProps<"fieldset">)}
+        >
+          {anatomy}
+        </fieldset>
+      ) : (
+        <section
+          data-slot="content"
+          data-as="section"
+          data-framed={framed}
+          data-frame-variant={frameVariant}
+          aria-labelledby={ariaLabelledBy}
+          className={cn(
+            "space-y-3",
+            framed && "rounded-lg border border-border p-4",
+            className,
+          )}
+          {...(props as ComponentProps<"section">)}
+        >
+          {anatomy}
+        </section>
+      )}
     </ContentContext.Provider>
   );
 }
@@ -158,6 +236,37 @@ export function ContentHeader({
     "ContentHeader",
     "Content",
   );
+  if (content.element === "fieldset") {
+    const nodes = Children.toArray(children);
+    if (
+      nodes.length !== 1 ||
+      !isValidElement(nodes[0]) ||
+      nodes[0].type !== ContentTitle
+    ) {
+      throw new Error(
+        "ContentHeader de fieldset exige somente um ContentTitle; contador, descrição e ações ficam fora da legenda.",
+      );
+    }
+    return (
+      <ContentHeaderContext.Provider value={content}>
+        <legend
+          data-slot="content-header"
+          className={cn(
+            content.framed &&
+              content.frameVariant === "default" &&
+              "float-left w-full",
+            content.framed &&
+              content.frameVariant === "legend" &&
+              "-ml-2 w-auto px-2",
+            className,
+          )}
+          {...props}
+        >
+          {children}
+        </legend>
+      </ContentHeaderContext.Provider>
+    );
+  }
   return (
     <ContentHeaderContext.Provider value={content}>
       <SurfaceHeader
@@ -195,14 +304,15 @@ export function ContentTitle({
   className,
   id,
   ...props
-}: HTMLAttributes<HTMLHeadingElement>): ReactElement {
+}: HTMLAttributes<HTMLElement>): ReactElement {
   const context = requiredContext(
     useContext(ContentHeaderContext),
     "ContentTitle",
     "ContentHeader",
   );
-  const Heading = headingTags[context.level];
-  usePageHeadingPresence(context.level === 1);
+  const Heading =
+    context.element === "fieldset" ? "span" : headingTags[context.level];
+  usePageHeadingPresence(context.element !== "fieldset" && context.level === 1);
   return (
     <Heading
       id={id ?? context.titleId}
@@ -279,6 +389,23 @@ export function ContentBody({
   className,
   ...props
 }: HTMLAttributes<HTMLDivElement>): ReactElement {
-  requiredContext(useContext(ContentContext), "ContentBody", "Content");
-  return <div data-slot="content-body" className={className} {...props} />;
+  const content = requiredContext(
+    useContext(ContentContext),
+    "ContentBody",
+    "Content",
+  );
+  return (
+    <div
+      data-slot="content-body"
+      className={cn(
+        content.element === "fieldset" && "space-y-3",
+        content.element === "fieldset" &&
+          content.framed &&
+          content.frameVariant === "default" &&
+          "clear-left pt-3",
+        className,
+      )}
+      {...props}
+    />
+  );
 }

package/src/ui/components/patterns/list.tsx

@@ -111,8 +111,13 @@ import {
   InputGroupInput,
 } from "../primitives/input-group.tsx";
 import { Separator } from "../primitives/separator.tsx";
-import { Label } from "../primitives/label.tsx";
-import { FieldGroup, FieldLegend, FieldSet } from "../primitives/field.tsx";
+import {
+  Field,
+  FieldGroup,
+  FieldLabel,
+  type FieldSetVariant,
+} from "../primitives/field.tsx";
+import { Content } from "./content-header.tsx";
 import { Search } from "lucide-react";
 import { Select, type SelectOption } from "../primitives/select.tsx";
 import {
@@ -307,6 +312,8 @@ export interface AdvancedFiltersLayout {
   columns?: 1 | 2 | 3;
   /** Ícone de cada seção, indexado pelo mesmo rótulo declarado nos filtros. */
   sectionIcons?: Record<string, ReactNode>;
+  /** Tratamento visual de cada seção. `framed` integra a legenda à moldura do conjunto. */
+  sectionVariant?: FieldSetVariant;
 }
 
 /** Uma view alternativa da MESMA listagem (board, galeria, lista, calendário…). A
@@ -1105,6 +1112,7 @@ function AdvancedFiltersDialog({
   filterDefaults,
   filterIcons,
   sectionIcons,
+  sectionVariant = "plain",
   cascade,
   columns = 1,
 }: {
@@ -1117,6 +1125,7 @@ function AdvancedFiltersDialog({
   filterDefaults?: Record<string, string> | undefined;
   filterIcons?: Record<string, ReactNode> | undefined;
   sectionIcons?: Record<string, ReactNode> | undefined;
+  sectionVariant?: FieldSetVariant | undefined;
   columns?: 1 | 2 | 3;
   /** A cascata do `depends` do pai — mudar um campo limpa os dependentes no draft. */
   cascade: (
@@ -1153,8 +1162,10 @@ function AdvancedFiltersDialog({
   }[columns];
 
   const field = ([name, spec]: [string, FilterSpec]): React.ReactElement => (
-    <div key={name} className="space-y-2">
-      <Label htmlFor={`filter-${name}`}>{text(spec.label, name)}</Label>
+    <Field key={name}>
+      <FieldLabel htmlFor={`filter-${name}`}>
+        {text(spec.label, name)}
+      </FieldLabel>
       <FilterField
         name={name}
         spec={spec}
@@ -1166,7 +1177,7 @@ function AdvancedFiltersDialog({
         defaultValue={filterDefaults?.[name]}
         icon={filterIcons?.[name]}
       />
-    </div>
+    </Field>
   );
 
   const clear = (): void => {
@@ -1194,14 +1205,32 @@ function AdvancedFiltersDialog({
         <DialogBody className="space-y-4">
           {sectioned ? (
             sections.map(([section, entries]) => (
-              <FieldSet key={section} className="gap-0">
-                <FieldLegend variant="section" icon={sectionIcons?.[section]}>
-                  {section}
-                </FieldLegend>
+              <Content
+                key={section}
+                as="fieldset"
+                framed={sectionVariant === "framed"}
+                frameVariant={
+                  sectionVariant === "framed" ? "legend" : "default"
+                }
+                title={
+                  <span className="flex items-center gap-2">
+                    {sectionIcons?.[section] !== undefined && (
+                      <span
+                        data-slot="content-title-icon"
+                        aria-hidden="true"
+                        className="inline-flex shrink-0 items-center justify-center text-muted-foreground [&_svg]:size-4"
+                      >
+                        {sectionIcons[section]}
+                      </span>
+                    )}
+                    {section}
+                  </span>
+                }
+              >
                 <FieldGroup className={cn("grid gap-4", gridColumns)}>
                   {entries.map(field)}
                 </FieldGroup>
-              </FieldSet>
+              </Content>
             ))
           ) : (
             <FieldGroup className={cn("grid gap-4", gridColumns)}>
@@ -1597,6 +1626,7 @@ export function ActionFilterBar({
             filterIcons={filterIcons}
             columns={advancedFilters?.columns}
             sectionIcons={advancedFilters?.sectionIcons}
+            sectionVariant={advancedFilters?.sectionVariant}
           />
         )}
       </div>
@@ -2111,7 +2141,7 @@ export function ActionList<TInput, TItem>({
   } else {
     content = (
       <Table
-        variant="framed"
+        variant="plain"
         className={tableStateActive ? "h-full" : undefined}
         containerClassName={
           tableFillsAvailableHeight
@@ -2122,7 +2152,7 @@ export function ActionList<TInput, TItem>({
         <TableHeader
           className={
             tableFillsAvailableHeight
-              ? "sticky top-0 z-10 bg-muted/30 dark:bg-input/30"
+              ? "sticky top-0 z-10 bg-background shadow-[inset_0_-0.0625rem_0_var(--border)] [&_tr]:border-b-0"
               : undefined
           }
         >
@@ -2270,7 +2300,7 @@ export function ActionList<TInput, TItem>({
     total !== undefined && !isError ? (
       <div
         data-slot="action-list-footer"
-        className="grid grid-cols-[1fr_auto_1fr] items-center gap-3 px-3 py-1.5 text-xs text-muted-foreground"
+        className="grid grid-cols-[1fr_auto_1fr] items-center gap-3 border-t border-border px-3 py-1.5 text-xs text-muted-foreground"
       >
         <span>
           Página {state.page} de {pages}

package/src/ui/components/primitives/detail.tsx

@@ -131,7 +131,7 @@ function DetailField({
       <dt
         data-slot="detail-field-label"
         className={cn(
-          'flex items-center gap-2.5 text-xs leading-snug font-medium text-muted-foreground group-data-[orientation=horizontal]/detail-group:text-sm',
+          'flex items-center gap-2.5 text-sm leading-snug font-medium text-muted-foreground',
           splitHorizontalField && 'bg-muted/30 p-3 dark:bg-input/30',
         )}
       >

package/src/ui/components/primitives/empty.tsx

@@ -1,6 +1,7 @@
 import { cva, type VariantProps } from "class-variance-authority"
 
 import { cn } from '../../lib/cn.ts'
+import { iconTileVariants } from './icon-tile.tsx'
 
 function Empty({ className, ...props }: React.ComponentProps<"div">) {
   return (
@@ -34,7 +35,7 @@ const emptyMediaVariants = cva(
     variants: {
       variant: {
         default: "bg-transparent",
-        icon: "flex size-10 shrink-0 items-center justify-center rounded-lg bg-muted text-foreground [&_svg:not([class*='size-'])]:size-6",
+        icon: iconTileVariants({ size: "lg", variant: "subtle" }),
       },
     },
     defaultVariants: {