@softize/opus 18.4.0 → 19.0.0

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

@@ -4,11 +4,13 @@ import {
   isValidElement,
   useContext,
   useId,
+  type ComponentProps,
   type HTMLAttributes,
   type ReactElement,
   type ReactNode,
 } from "react";
 import { cn } from "../../lib/cn.ts";
+import { headingTags } from "./heading-level.ts";
 import { usePageHeadingPresence } from "./page-heading-context.tsx";
 import {
   SurfaceHeader,
@@ -18,8 +20,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 +45,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 +84,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 +100,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 +159,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 +237,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
@@ -182,27 +292,19 @@ export function ContentHeader({
   );
 }
 
-const headingTags = {
-  1: "h1",
-  2: "h2",
-  3: "h3",
-  4: "h4",
-  5: "h5",
-  6: "h6",
-} as const;
-
 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 +381,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/heading-level.ts

@@ -0,0 +1,16 @@
+/**
+ * Nível de heading (interno): hierarquia do documento, separada do tamanho visual.
+ *
+ * A ADR 0023 fixa a regra: `h1`–`h6` expressam hierarquia; a escala do título vem da
+ * família e do layout. As duas decisões nunca se misturam num mesmo valor.
+ */
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export const headingTags = {
+  1: "h1",
+  2: "h2",
+  3: "h3",
+  4: "h4",
+  5: "h5",
+  6: "h6",
+} as const satisfies Record<HeadingLevel, `h${HeadingLevel}`>;

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,18 +2141,21 @@ export function ActionList<TInput, TItem>({
   } else {
     content = (
       <Table
-        variant="framed"
+        variant="plain"
         className={tableStateActive ? "h-full" : undefined}
         containerClassName={
+          // Quem rola é a linha de resultados, acima: aqui o contêiner abre mão da
+          // rolagem horizontal para não virar a referência do `sticky` do cabeçalho.
+          // `h-full` só no estado sem linhas, para a moldura vazia ocupar a altura.
           tableFillsAvailableHeight
-            ? "absolute inset-0 overflow-auto"
+            ? cn("overflow-x-visible", tableStateActive && "h-full")
             : undefined
         }
       >
         <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
           }
         >
@@ -2260,7 +2293,14 @@ export function ActionList<TInput, TItem>({
     ) : null;
 
   // — Rodapé (o estilo da casa): Página X de Y à esquerda · pager CENTRALIZADO ·
-  //   total à direita (grid de 3 colunas com laterais 1fr = centro geométrico) —
+  //   total à direita (grid de 3 colunas com laterais 1fr = centro geométrico).
+  //   Encosta na última linha: a borda de cima é o fecho da tabela, não a de um
+  //   bloco solto, então o rodapé não entra no `gap` da pilha.
+  //   Altura: 2.5rem de piso (a mesma do `TableHead`) para a faixa não mudar de
+  //   tamanho quando o pager aparece — ele ocupa 1.75rem e cabe dentro do piso.
+  //   O padding fica em 0.25rem só para o dia em que o conteúdo passar disso:
+  //   com `py-2` o padding empurraria o pager para fora e a faixa voltaria a
+  //   crescer —
   const pages =
     total !== undefined
       ? Math.max(1, Math.ceil(total / (state.limit ?? pageSize)))
@@ -2270,7 +2310,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 min-h-10 grid-cols-[1fr_auto_1fr] items-center gap-3 border-t border-border px-3 py-1 text-xs text-muted-foreground"
       >
         <span>
           Página {state.page} de {pages}
@@ -2338,19 +2378,28 @@ export function ActionList<TInput, TItem>({
         {toolbar}
         {beforeContent}
         {selectionBar}
-        {/* Refetch com a lista já na tela: esmaece e trava interação até chegar. */}
-        <div
-          aria-busy={busy}
-          className={cn(
-            layout === "fill" && "relative flex min-h-0 flex-1 flex-col",
-            layout === "fill" &&
-              (tableFillsAvailableHeight ? "overflow-hidden" : "overflow-auto"),
-            busy && items.length > 0 && "pointer-events-none opacity-60",
-          )}
-        >
-          {body}
+        {/* Tabela e rodapé formam um bloco só: o `gap` da pilha separa a barra de
+            ferramentas do conteúdo, nunca o conteúdo do seu próprio rodapé. Duas
+            linhas: a dos resultados absorve a altura que sobra, a do rodapé se mede
+            pelo conteúdo. Em `flow` a primeira linha também é `1fr`, mas o bloco não
+            tem altura própria e ela vira a altura do conteúdo. */}
+        <div className={cn("grid min-h-0 grid-rows-[1fr_auto]", layout === "fill" && "flex-1")}>
+          {/* A rolagem mora aqui, nos dois eixos: é este elemento que o `sticky` do
+              cabeçalho enxerga. Um contêiner de rolagem entre ele e a tabela roubaria
+              essa referência e o cabeçalho voltaria a subir junto com as linhas.
+              Refetch com a lista já na tela: esmaece e trava interação até chegar. */}
+          <div
+            aria-busy={busy}
+            className={cn(
+              "min-h-0",
+              layout === "fill" && "overflow-auto",
+              busy && items.length > 0 && "pointer-events-none opacity-60",
+            )}
+          >
+            {body}
+          </div>
+          {footer}
         </div>
-        {footer}
         {confirming !== null && (
           <Dialog
             mode="alert"