@softize/opus 22.2.0 → 24.0.0

package/src/ui/components/patterns/action-form-card.tsx

@@ -1,19 +1,19 @@
 /**
- * <ActionFormCard /> — o ActionForm dentro de um Card do Opus (header / conteúdo / rodapé),
- * pra estruturar uma seção da página como painel. Segue o padrão do CARD (não a chrome de
- * modal): sem divisor nem faixa, com o respiro do Card. Pra form em overlay, use o
- * ActionFormDialog; pra form cru (sem chrome), o ActionForm direto.
+ * <ActionFormCard /> — o ActionForm dentro de uma Surface elevada (header / conteúdo /
+ * rodapé), pra estruturar uma seção da página como painel. Segue o layout contínuo (não a
+ * chrome de modal): sem divisor nem faixa. Pra form em overlay, use o ActionFormDialog; pra
+ * form cru (sem chrome), o ActionForm direto.
  */
-import {
-  Card,
-  CardBody,
-  CardDescription,
-  CardFooter,
-  CardHeader,
-  CardTitle,
-} from "../primitives/card.tsx";
 import { ActionForm, type ActionFormProps } from "./form.tsx";
 import type { HeadingLevel } from "./heading-level.ts";
+import {
+  Surface,
+  SurfaceBody,
+  SurfaceDescription,
+  SurfaceFooter,
+  SurfaceHeader,
+  SurfaceTitle,
+} from "./surface.tsx";
 import { ButtonGroup } from "../primitives/button-group.tsx";
 
 export interface ActionFormCardProps<
@@ -23,49 +23,62 @@ export interface ActionFormCardProps<
   /** Título do header do card. Sem ele, o card começa direto no conteúdo. */
   title?: string;
   /**
-   * Nível semântico do título (`h1`–`h6`), repassado ao `CardTitle` como `level`. Sem
-   * ele vale o `h3` do Card. Muda só a hierarquia do documento; a escala visual continua
-   * a do Card.
+   * Nível semântico do título (`h1`–`h6`), repassado à `Surface` como `level`. Sem ele
+   * vale `h3`: o card costuma ser uma seção dentro de uma página que já tem `h1` e `h2`.
    */
   titleLevel?: HeadingLevel;
-  /** Subtítulo opcional, abaixo do título. */
+  /** Subtítulo opcional, abaixo do título. Exige `title`. */
   description?: string;
-  /** Classes do Card (a superfície). `className` vai pro <form>. */
+  /** Classes da superfície. `className` vai pro <form>. */
   cardClassName?: string;
 }
 
 export function ActionFormCard<TInput extends Record<string, unknown>, TData>({
   title,
-  titleLevel,
+  titleLevel = 3,
   description,
   cardClassName,
   ...rest
 }: ActionFormCardProps<TInput, TData>) {
+  if (description !== undefined && title === undefined) {
+    throw new Error(
+      "ActionFormCard exige title quando description é informada.",
+    );
+  }
   return (
-    <Card className={cardClassName}>
-      {(title !== undefined || description !== undefined) && (
-        <CardHeader>
-          {title !== undefined && (
-            <CardTitle level={titleLevel}>{title}</CardTitle>
-          )}
-          {description !== undefined && (
-            <CardDescription>{description}</CardDescription>
-          )}
-        </CardHeader>
-      )}
+    <Surface
+      framed
+      elevation="raised"
+      level={titleLevel}
+      className={cardClassName}
+    >
+      {/* As três regiões são irmãs dentro do <form>: o ritmo e o respiro de cada uma
+          derivam da vizinhança, e os botões precisam ficar dentro do form. */}
       <ActionForm
         {...rest}
-        body={(fields) => <CardBody>{fields}</CardBody>}
+        body={(fields) => (
+          <>
+            {title !== undefined && (
+              <SurfaceHeader>
+                <SurfaceTitle>{title}</SurfaceTitle>
+                {description !== undefined && (
+                  <SurfaceDescription>{description}</SurfaceDescription>
+                )}
+              </SurfaceHeader>
+            )}
+            <SurfaceBody>{fields}</SurfaceBody>
+          </>
+        )}
         footer={(actions) => (
-          <CardFooter className="justify-end">
+          <SurfaceFooter>
             {rest.onCancel === undefined ? (
               actions
             ) : (
               <ButtonGroup mode="spaced">{actions}</ButtonGroup>
             )}
-          </CardFooter>
+          </SurfaceFooter>
         )}
       />
-    </Card>
+    </Surface>
   );
 }

package/src/ui/components/patterns/action-list-dialog.tsx

@@ -86,14 +86,12 @@ export function ActionListDialog<
         </DialogHeader>
         <DialogBody>
           {intro !== undefined && (
-            <div id={introId} className="mb-4">
-              {intro}
-            </div>
+            <div id={introId}>{intro}</div>
           )}
           {(note !== undefined || actions !== undefined) && (
             <div
               data-slot="action-list-dialog-toolbar"
-              className="mb-2 flex min-h-8 items-center justify-between gap-4"
+              className="flex min-h-8 items-center justify-between gap-4"
             >
               <div className="min-w-0 text-xs text-muted-foreground/70">{note}</div>
               {actions}

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

@@ -284,7 +284,9 @@ export function DialogHost(): React.ReactElement {
             <DialogTitle>{current.title}</DialogTitle>
           </DialogHeader>
           {current.body !== undefined && (
-            <DialogBody id={bodyId}>{current.body}</DialogBody>
+            <DialogBody id={bodyId}>
+              <div>{current.body}</div>
+            </DialogBody>
           )}
           {current.kind === "prompt" && (
             <Input

package/src/ui/components/patterns/fill-region.ts

@@ -7,15 +7,16 @@
  * coluna flexível. Este módulo faz essa cadeia se formar sem classes no consumidor:
  *
  * - a raiz (`FillRoot`) publica o contexto;
- * - os elos canônicos (`PageBody`, `Content`, `ContentBody`, o corpo da `Presentation`)
- *   leem o contexto com `useFillRegion` e o republicam para os filhos;
+ * - os elos canônicos (`PageBody`, `Surface` sem elevação, `SurfaceBody`, o corpo da
+ *   `Presentation`) leem o contexto com `useFillRegion` e o republicam para os filhos;
  * - a folha (`ActionList`) usa `useFillLeaf`: assume `fill` por padrão quando o elemento
  *   pai é um elo e se registra na cadeia;
- * - um elo só vira coluna flexível quando uma folha se registrou abaixo dele. Irmãos sem
- *   folha mantêm a altura do próprio conteúdo, e uma página `fill` sem lista não muda;
- * - superfícies com anatomia própria (Card, Dialog, Drawer, Pane) cortam a cadeia com
- *   `FillBoundary`: a altura delas é decisão delas, inclusive quando um portal as renderiza
- *   dentro de uma página `fill`.
+ * - os bodies estruturais já são colunas para governar o ritmo; quando uma folha se registra,
+ *   os elos também passam a ocupar a folga disponível. Irmãos sem folha mantêm a altura do
+ *   próprio conteúdo, e uma página `fill` sem lista não muda;
+ * - superfícies com altura própria (`Surface elevation="raised"`, Dialog, Drawer, Pane)
+ *   cortam a cadeia com `FillBoundary`: a altura delas é decisão delas, inclusive quando um
+ *   portal as renderiza dentro de uma página `fill`.
  *
  * O registro acontece em `useLayoutEffect`, então as classes chegam antes da primeira pintura.
  */

package/src/ui/components/patterns/form-dialog.tsx

@@ -66,9 +66,7 @@ export function ActionFormDialog<
           body={(fields) => (
             <DialogBody>
               {intro !== undefined && (
-                <div id={introId} className="mb-4">
-                  {intro}
-                </div>
+                <div id={introId}>{intro}</div>
               )}
               {fields}
             </DialogBody>

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

@@ -49,7 +49,8 @@ import {
 } from "../primitives/tooltip.tsx";
 import { Info } from "lucide-react";
 import { Select, type SelectOption } from "../primitives/select.tsx";
-import { ToggleGroup, ToggleGroupItem } from "../primitives/toggle-group.tsx";
+import { Toggle } from "../primitives/toggle.tsx";
+import { ToggleGroup } from "../primitives/toggle-group.tsx";
 import {
   Field,
   FieldError,
@@ -464,14 +465,14 @@ export function ActionFormField({
             value={(formValues[name] as string[] | undefined) ?? []}
             onValueChange={(value) => setValue(value)}
             variant="outline"
-            spacing={2}
+            mode="spaced"
             aria-labelledby={`${name}-label`}
             aria-invalid={errorMessage !== undefined}
             aria-describedby={describedBy}
             className="grid w-full grid-cols-[repeat(auto-fit,minmax(min(100%,12rem),1fr))] items-stretch gap-2"
           >
             {options.map((option) => (
-              <ToggleGroupItem
+              <Toggle
                 key={option.value}
                 value={option.value}
                 disabled={option.disabled}
@@ -488,7 +489,7 @@ export function ActionFormField({
                     </span>
                   )}
                 </span>
-              </ToggleGroupItem>
+              </Toggle>
             ))}
           </ToggleGroup>
         ) : (
@@ -502,7 +503,7 @@ export function ActionFormField({
               }
             }}
             variant="outline"
-            spacing={2}
+            mode="spaced"
             aria-labelledby={`${name}-label`}
             aria-required={effectiveKind.required}
             aria-invalid={errorMessage !== undefined}
@@ -510,7 +511,7 @@ export function ActionFormField({
             className="grid w-full grid-cols-[repeat(auto-fit,minmax(min(100%,12rem),1fr))] items-stretch gap-2"
           >
             {options.map((option) => (
-              <ToggleGroupItem
+              <Toggle
                 key={option.value}
                 value={option.value}
                 disabled={option.disabled}
@@ -527,7 +528,7 @@ export function ActionFormField({
                     </span>
                   )}
                 </span>
-              </ToggleGroupItem>
+              </Toggle>
             ))}
           </ToggleGroup>
         )

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

@@ -111,6 +111,7 @@ import {
   InputGroupButton,
   InputGroupInput,
 } from "../primitives/input-group.tsx";
+import { iconPickerIcons } from "../primitives/icon-picker.tsx";
 import { Separator } from "../primitives/separator.tsx";
 import {
   Field,
@@ -118,7 +119,7 @@ import {
   FieldLabel,
   type FieldSetVariant,
 } from "../primitives/field.tsx";
-import { Content } from "./content-header.tsx";
+import { Surface } from "./surface.tsx";
 import { Search } from "lucide-react";
 import { Select, type SelectOption } from "../primitives/select.tsx";
 import {
@@ -129,7 +130,8 @@ import {
   TableHeader,
   TableRow,
 } from "../primitives/table.tsx";
-import { ToggleGroup, ToggleGroupItem } from "../primitives/toggle-group.tsx";
+import { Toggle } from "../primitives/toggle.tsx";
+import { ToggleGroup } from "../primitives/toggle-group.tsx";
 import {
   Tooltip,
   TooltipContent,
@@ -347,7 +349,7 @@ export interface ActionListProps<TInput, TItem> {
   /**
    * `fill` ocupa a altura disponível e mantém a rolagem dentro da região de resultados.
    * Sem valor, vale `fill` quando o elemento pai repassa a altura de uma `Page` ou
-   * `Presentation` em `fill` — `PageBody`, `ContentBody` ou o corpo da Presentation — e
+   * `Presentation` em `fill` — `PageBody`, `SurfaceBody` ou o corpo da Presentation — e
    * `flow` nos demais casos (ADR 0024).
    */
   layout?: "flow" | "fill";
@@ -479,7 +481,23 @@ function dictOptionsFor(
   if (spec.options?.kind !== "dictionary") return [];
   const dict = dicts[spec.options.ref];
   if (dict === undefined) return [];
-  return dict.options().map((o) => ({ value: o.value, label: o.label }));
+  return dict.options().map((o) => {
+    const Icon = o.icon === undefined ? undefined : iconPickerIcons[o.icon];
+    return {
+      value: o.value,
+      label: o.label,
+      ...(Icon === undefined
+        ? {}
+        : {
+            content: (
+              <>
+                <Icon aria-hidden="true" />
+                <span>{o.label}</span>
+              </>
+            ),
+          }),
+    };
+  });
 }
 
 /** Opções vindas de uma action de lookup (`options.kind: 'lookup'`): o Select chama
@@ -571,6 +589,41 @@ function FilterField({
   const changedFromDefault = singleValue !== defaultValue;
   const acceptsEmptyValue = spec.allowEmpty !== false;
 
+  if (
+    spec.type === "select" &&
+    spec.multiple !== true &&
+    spec.presentation === "toggle"
+  ) {
+    const ALL = "__all__";
+    const toggleValue = singleValue === "" ? ALL : singleValue;
+    return (
+      <ToggleGroup
+        type="single"
+        mode="segmented"
+        id={`filter-${name}`}
+        value={toggleValue}
+        onValueChange={(next) => {
+          // O grupo sempre preserva uma escolha ativa. Quando vazio é permitido,
+          // a opção explícita representa esse estado em vez de desmarcar o item atual.
+          if (next === "") return;
+          onChange(next === ALL ? "" : next);
+        }}
+        aria-label={label}
+        disabled={!enabled}
+        className={className ?? "max-w-full"}
+      >
+        {acceptsEmptyValue && (
+          <Toggle value={ALL}>{text(spec.placeholder, "Todos")}</Toggle>
+        )}
+        {base.map((option) => (
+          <Toggle key={option.value} value={option.value}>
+            {option.content ?? option.label}
+          </Toggle>
+        ))}
+      </ToggleGroup>
+    );
+  }
+
   if (spec.multiple === true) {
     return (
       <Select
@@ -993,7 +1046,7 @@ function PeriodControl({
             variant={embedded ? "ghost" : "outline"}
             data-slot="action-list-period"
             className={cn(
-              "relative max-w-full gap-1.5 overflow-hidden bg-muted/30 px-3 hover:bg-muted/30 hover:text-foreground dark:bg-input/30 dark:hover:bg-input/30",
+              "relative max-w-full gap-1.5 overflow-hidden bg-control px-3 hover:bg-interaction-hover hover:text-foreground",
               // O X e o chevron ocupam posições explícitas na ponta do controle. O
               // padding reserva os dois sem depender da largura do texto selecionado.
               clearable && "pr-16",
@@ -1217,23 +1270,20 @@ function AdvancedFiltersDialog({
         <DialogHeader>
           <DialogTitle>Filtros</DialogTitle>
         </DialogHeader>
-        <DialogBody className="space-y-4">
+        <DialogBody>
           {sectioned ? (
             sections.map(([section, entries]) => (
-              <Content
+              <Surface
                 key={section}
                 as="fieldset"
                 framed={sectionVariant === "framed"}
-                frameVariant={
-                  sectionVariant === "framed" ? "legend" : "default"
-                }
                 title={section}
                 media={sectionIcons?.[section]}
               >
                 <FieldGroup className={cn("grid gap-4", gridColumns)}>
                   {entries.map(field)}
                 </FieldGroup>
-              </Content>
+              </Surface>
             ))
           ) : (
             <FieldGroup className={cn("grid gap-4", gridColumns)}>
@@ -1431,7 +1481,7 @@ export function ActionFilterBar({
                   <div
                     data-slot="action-filter-period-group"
                     className={cn(
-                      "flex min-h-9 w-fit min-w-0 max-w-full items-center rounded-md border border-input bg-muted/30 text-foreground transition-[color,box-shadow] focus-within:border-ring focus-within:ring-[0.1875rem] focus-within:ring-ring/50 has-[[data-state=open]]:border-ring has-[[data-state=open]]:ring-[0.1875rem] has-[[data-state=open]]:ring-ring/50 dark:bg-input/30",
+                      "flex min-h-9 w-fit min-w-0 max-w-full items-center rounded-md border border-input bg-control text-foreground transition-[color,box-shadow] focus-within:border-ring focus-within:ring-[0.1875rem] focus-within:ring-ring/50 has-[[data-state=open]]:border-ring has-[[data-state=open]]:ring-[0.1875rem] has-[[data-state=open]]:ring-ring/50",
                       !periodGroupClearable && "pr-3",
                     )}
                   >
@@ -1981,9 +2031,9 @@ export function ActionList<TInput, TItem>({
                 {viewEntries.map(([key, label, icon]) => (
                   <Tooltip key={key}>
                     <TooltipTrigger asChild>
-                      <ToggleGroupItem value={key} aria-label={label}>
+                      <Toggle value={key} aria-label={label}>
                         {icon ?? label}
-                      </ToggleGroupItem>
+                      </Toggle>
                     </TooltipTrigger>
                     <TooltipContent>{label}</TooltipContent>
                   </Tooltip>

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

@@ -24,12 +24,15 @@ import { createPortal } from "react-dom";
 import { ArrowLeft } from "lucide-react";
 import { cn } from "../../lib/cn.ts";
 import { Button } from "../primitives/button.tsx";
-import { Content } from "./content-header.tsx";
+import { Surface } from "./surface.tsx";
 import {
   PageHeadingPresenceProvider,
   usePageHeadingPresence,
 } from "./page-heading-context.tsx";
-import { SurfaceHeader, surfaceHeaderClasses } from "./surface-header.tsx";
+import {
+  StructuralHeader,
+  structuralHeaderClasses,
+} from "./structural-header.tsx";
 import { PageState, PageStatePresenceProvider } from "./page-state.tsx";
 import { FillRoot, fillRegionClassName, useFillRegion } from "./fill-region.ts";
 
@@ -137,7 +140,7 @@ interface PageBaseProps extends Omit<
   className?: string;
   /**
    * `fill` limita a página à altura do shell para que regiões internas assumam a rolagem.
-   * A altura chega sozinha a uma `ActionList` composta por `PageBody` e `Content` (ADR 0024).
+   * A altura chega sozinha a uma `ActionList` composta por `PageBody` e `Surface` (ADR 0024).
    */
   layout?: "flow" | "fill";
 }
@@ -198,7 +201,7 @@ function countPageBodyHeadings(node: ReactNode): {
       return {
         content:
           total.content +
-          (child.type === Content && props.level === 1 ? 1 : 0) +
+          (child.type === Surface && props.level === 1 ? 1 : 0) +
           nested.content,
         state: total.state + nested.state,
       };
@@ -211,7 +214,7 @@ function hasOpaquePageBodyContent(node: ReactNode): boolean {
   return Children.toArray(node).some((child) => {
     if (!isValidElement(child)) return false;
     if (typeof child.type !== "string") {
-      return child.type !== Content && child.type !== PageState;
+      return child.type !== Surface && child.type !== PageState;
     }
     return hasOpaquePageBodyContent(
       (child.props as { children?: ReactNode }).children,
@@ -323,7 +326,7 @@ export function Page({
     );
     if (headingSources > 1 || (headingSources === 0 && !hasOpaqueBodyContent)) {
       throw new Error(
-        "Page explícito exige exatamente um heading principal em PageHeader, Content level={1} ou PageState ativo dentro de PageBody.",
+        "Page explícito exige exatamente um heading principal em PageHeader, Surface level={1} ou PageState ativo dentro de PageBody.",
       );
     }
   }
@@ -332,7 +335,7 @@ export function Page({
     if (integralState !== hasActiveIntegralState) return;
     if (headingCount.current !== 1) {
       throw new Error(
-        "Page explícito exige exatamente um heading principal em PageHeader, Content level={1} ou PageState ativo dentro de PageBody.",
+        "Page explícito exige exatamente um heading principal em PageHeader, Surface level={1} ou PageState ativo dentro de PageBody.",
       );
     }
   });
@@ -452,7 +455,7 @@ export function PageHeader({
   }
   return (
     <PageHeaderContext.Provider value>
-      <SurfaceHeader
+      <StructuralHeader
         name="PageHeader"
         slot="page"
         slots={{
@@ -472,7 +475,7 @@ export function PageHeader({
         )}
         {structuralChildren}
         {mergedActions}
-      </SurfaceHeader>
+      </StructuralHeader>
     </PageHeaderContext.Provider>
   );
 }
@@ -487,7 +490,7 @@ export function PageTitle({
   return (
     <h1
       data-slot="page-title"
-      className={cn(surfaceHeaderClasses.page.title, className)}
+      className={cn(structuralHeaderClasses.page.title, className)}
       {...props}
     />
   );
@@ -503,7 +506,7 @@ export function PageActions({
   const actions = (
     <div
       data-slot="page-actions"
-      className={cn(surfaceHeaderClasses.page.actions, className)}
+      className={cn(structuralHeaderClasses.page.actions, className)}
       {...props}
     />
   );
@@ -579,6 +582,7 @@ export function PageBody({
       data-slot="page-body"
       {...fill.attributes}
       className={cn(
+        "flex flex-col gap-6 *:shrink-0",
         (integralState || fill.filling) && fillRegionClassName,
         className,
       )}