@softize/opus 18.1.0 → 18.2.0

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

@@ -1,13 +1,15 @@
 import {
   useCallback,
+  useEffect,
   useState,
   type ReactElement,
   type ReactNode,
 } from "react";
 import { createPortal } from "react-dom";
-import { ArrowLeft, Braces } from "lucide-react";
+import { ArrowLeft, Braces, MessageCircle } from "lucide-react";
 import type {
   PresentationActionRegistry,
+  PresentationActionBody,
   PresentationBindingContext,
   PresentationCommand,
   PresentationDiagnostic,
@@ -19,6 +21,7 @@ import type {
 import {
   applyPresentationEffects,
   createPresentationInspectionSnapshot,
+  isPresentationActionBody,
   openPresentation,
   resolvePresentationBindings,
 } from "../../../core/presentation.ts";
@@ -75,6 +78,7 @@ import {
   ContentHeader,
   ContentTitle,
 } from "./content-header.tsx";
+import { SurfaceAssistant } from "./surface-assistant.tsx";
 
 interface PresentationFrameProps {
   surface: PresentationSurface;
@@ -90,6 +94,11 @@ interface PresentationFrameProps {
   className?: string;
   bodyClassName?: string;
   listBody?: boolean;
+  contentOwnsHeading?: boolean;
+  assistantOpen?: boolean;
+  assistantLabel?: string;
+  assistantAction?: ReactNode;
+  assistantPanel?: ReactNode;
 }
 
 const bodyClassName =
@@ -124,6 +133,11 @@ function PresentationFrame({
   className,
   bodyClassName: bodyClassNameProp,
   listBody = false,
+  contentOwnsHeading = false,
+  assistantOpen = false,
+  assistantLabel,
+  assistantAction,
+  assistantPanel,
 }: PresentationFrameProps): ReactElement {
   const insidePageShell = useInsidePageShell();
   const [footerTarget, setFooterTarget] = useState<HTMLElement | null>(null);
@@ -153,6 +167,20 @@ function PresentationFrame({
       {typeof children === "function" ? children(footerTarget) : children}
     </div>
   );
+  const withAssistant = (content: ReactElement): ReactElement =>
+    assistantLabel === undefined || assistantPanel === undefined ? (
+      content
+    ) : (
+      <SurfaceAssistant
+        open={assistantOpen}
+        assistantLabel={assistantLabel}
+        assistant={assistantPanel}
+        className="min-h-0 flex-1"
+        contentClassName="flex min-h-0 flex-col"
+      >
+        {content}
+      </SurfaceAssistant>
+    );
 
   if (surface === "page") {
     if (listBody) {
@@ -171,13 +199,20 @@ function PresentationFrame({
       );
       return (
         <Page className={cn("flex min-h-full flex-col", className)}>
-          {navigation === undefined ? null : (
+          {navigation === undefined && assistantAction === undefined ? null : (
             <PageHeader>
-              <PageNavigation>{navigation}</PageNavigation>
+              {navigation === undefined ? null : (
+                <PageNavigation>{navigation}</PageNavigation>
+              )}
+              {assistantAction === undefined ? null : (
+                <PageActions>{assistantAction}</PageActions>
+              )}
             </PageHeader>
           )}
-          <PageBody className="min-h-0 flex-1 overflow-y-auto">
-            {content}
+          <PageBody className="min-h-0 flex-1 overflow-hidden">
+            {withAssistant(
+              <div className="h-full overflow-y-auto">{content}</div>,
+            )}
           </PageBody>
           {hasFooter ? <PageFooter>{renderFooterActions()}</PageFooter> : null}
         </Page>
@@ -186,22 +221,36 @@ function PresentationFrame({
     if (insidePageShell) {
       return (
         <Page className={cn("flex min-h-full flex-col", className)}>
-          {navigation === undefined && headerActions === undefined ? null : (
+          {navigation === undefined &&
+          headerActions === undefined &&
+          assistantAction === undefined ? null : (
             <PageHeader>
               {navigation === undefined ? null : (
                 <PageNavigation>{navigation}</PageNavigation>
               )}
-              {headerActions === undefined ? null : (
+              {headerActions === undefined &&
+              assistantAction === undefined ? null : (
                 <PageActions>
-                  <PresentationActions>{headerActions}</PresentationActions>
+                  <PresentationActions>
+                    {headerActions}
+                    {assistantAction}
+                  </PresentationActions>
                 </PageActions>
               )}
             </PageHeader>
           )}
-          <PageIntro>
-            <PageTitle>{title}</PageTitle>
-          </PageIntro>
-          <PageBody className="min-h-0 flex-1 overflow-y-auto">{body}</PageBody>
+          <PageBody className="min-h-0 flex-1 overflow-hidden">
+            {withAssistant(
+              <div className="flex h-full min-h-0 flex-col overflow-y-auto">
+                {contentOwnsHeading ? null : (
+                  <PageIntro>
+                    <PageTitle>{title}</PageTitle>
+                  </PageIntro>
+                )}
+                {body}
+              </div>,
+            )}
+          </PageBody>
           {hasFooter ? <PageFooter>{renderFooterActions()}</PageFooter> : null}
         </Page>
       );
@@ -218,14 +267,20 @@ function PresentationFrame({
             <PageNavigation>{navigation}</PageNavigation>
           )}
           <PageTitle className="text-lg leading-none">{title}</PageTitle>
-          {headerActions === undefined ? null : (
+          {headerActions === undefined &&
+          assistantAction === undefined ? null : (
             <PageActions>
-              <PresentationActions>{headerActions}</PresentationActions>
+              <PresentationActions>
+                {headerActions}
+                {assistantAction}
+              </PresentationActions>
             </PageActions>
           )}
         </PageHeader>
-        <PageBody className="min-h-0 flex-1 overflow-y-auto px-8 py-8">
-          {body}
+        <PageBody className="min-h-0 flex-1 overflow-hidden">
+          {withAssistant(
+            <div className="h-full overflow-y-auto px-8 py-8">{body}</div>,
+          )}
         </PageBody>
         {hasFooter ? <PageFooter>{renderFooterActions()}</PageFooter> : null}
       </Page>
@@ -242,7 +297,10 @@ function PresentationFrame({
         }}
       >
         <DialogContent
-          className={className}
+          className={cn(
+            assistantOpen ? "h-[min(48rem,85vh)] max-w-5xl" : undefined,
+            className,
+          )}
           aria-describedby={undefined}
           closeDisabled={blocked}
           onEscapeKeyDown={(event) => {
@@ -252,17 +310,23 @@ function PresentationFrame({
             if (blocked) event.preventDefault();
           }}
         >
-          <DialogHeader>
-            {navigation}
-            <DialogTitle className="truncate">{title}</DialogTitle>
-            {headerActions === undefined ? null : (
-              <PresentationActions>{headerActions}</PresentationActions>
-            )}
-          </DialogHeader>
-          <DialogBody>{body}</DialogBody>
-          {hasFooter ? (
-            <DialogFooter>{renderFooterActions()}</DialogFooter>
-          ) : null}
+          <div className="flex h-full min-h-0 flex-col">
+            <DialogHeader>
+              {navigation}
+              <DialogTitle className="truncate">{title}</DialogTitle>
+              {headerActions === undefined &&
+              assistantAction === undefined ? null : (
+                <PresentationActions>
+                  {headerActions}
+                  {assistantAction}
+                </PresentationActions>
+              )}
+            </DialogHeader>
+            {withAssistant(<DialogBody>{body}</DialogBody>)}
+            {hasFooter ? (
+              <DialogFooter>{renderFooterActions()}</DialogFooter>
+            ) : null}
+          </div>
         </DialogContent>
       </Dialog>
     );
@@ -277,7 +341,12 @@ function PresentationFrame({
       }}
     >
       <DrawerContent
-        className={className}
+        className={cn(
+          assistantOpen
+            ? "w-[min(80rem,calc(100%-2rem))] max-w-none"
+            : undefined,
+          className,
+        )}
         aria-describedby={undefined}
         closeDisabled={blocked}
         onEscapeKeyDown={(event) => {
@@ -287,22 +356,33 @@ function PresentationFrame({
           if (blocked) event.preventDefault();
         }}
       >
-        <DrawerHeader>
-          {navigation}
-          <DrawerTitle className="truncate">{title}</DrawerTitle>
-          {headerActions === undefined ? null : (
-            <PresentationActions>{headerActions}</PresentationActions>
-          )}
-        </DrawerHeader>
-        <DrawerBody>{body}</DrawerBody>
-        {hasFooter ? (
-          <DrawerFooter>{renderFooterActions()}</DrawerFooter>
-        ) : null}
+        <div className="flex h-full min-h-0 flex-col">
+          <DrawerHeader>
+            {navigation}
+            <DrawerTitle className="truncate">{title}</DrawerTitle>
+            {headerActions === undefined &&
+            assistantAction === undefined ? null : (
+              <PresentationActions>
+                {headerActions}
+                {assistantAction}
+              </PresentationActions>
+            )}
+          </DrawerHeader>
+          {withAssistant(<DrawerBody>{body}</DrawerBody>)}
+          {hasFooter ? (
+            <DrawerFooter>{renderFooterActions()}</DrawerFooter>
+          ) : null}
+        </div>
       </DrawerContent>
     </Drawer>
   );
 }
 
+export interface PresentationAssistantRuntime {
+  icon?: ReactNode;
+  render: (controls: { close: () => void }) => ReactNode;
+}
+
 export interface PresentationProps {
   /** Definição estática registrada e publicada no manifest. */
   definition: PresentationDefinition;
@@ -325,6 +405,10 @@ export interface PresentationProps {
   onOpenChange?: (open: boolean) => void;
   className?: string;
   bodyClassName?: string;
+  /** Conteúdo React da boundary declarada por `body.component`. */
+  children?: ReactNode;
+  /** Painel runtime; a página fecha sobre os dados do recurso que ela carregou. */
+  assistant?: PresentationAssistantRuntime;
 }
 
 function actionLabel(action: { name: string; label?: unknown }): string {
@@ -394,6 +478,8 @@ export function Presentation({
   onOpenChange,
   className,
   bodyClassName: bodyClassNameProp,
+  children,
+  assistant,
 }: PresentationProps): ReactElement {
   if (definition.id !== invocation.presentationId) {
     throw new Error(
@@ -404,16 +490,17 @@ export function Presentation({
     ReadonlySet<PresentationCommand>
   >(() => new Set());
   const [bodyLoading, setBodyLoading] = useState(false);
+  const [assistantOpen, setAssistantOpen] = useState(false);
+  useEffect(() => {
+    setAssistantOpen(false);
+  }, [definition.id, invocation.surface]);
   const context: PresentationBindingContext = {
     ...bindingContext,
     route: bindingContext?.route ?? invocation.input,
   };
 
   const applyEffects = useCallback(
-    (
-      effects: PresentationDefinition["body"]["onSuccess"],
-      result?: unknown,
-    ): void => {
+    (effects: PresentationActionBody["onSuccess"], result?: unknown): void => {
       const next = applyPresentationEffects(
         invocation,
         effects,
@@ -541,23 +628,51 @@ export function Presentation({
     );
   };
 
-  const bodyAction = actions[definition.body.action];
-  if (bodyAction === undefined) {
-    throw new Error(`Action “${definition.body.action}” não registrada.`);
+  const actionBody = isPresentationActionBody(definition.body)
+    ? definition.body
+    : null;
+  const bodyAction = actionBody === null ? null : actions[actionBody.action];
+  if (actionBody !== null && bodyAction === undefined) {
+    throw new Error(`Action “${actionBody.action}” não registrada.`);
   }
-  const bodyInput = resolvePresentationBindings(
-    definition.body.input,
-    context,
-  ) as Record<string, unknown>;
+  if (actionBody === null && children === undefined) {
+    throw new Error(
+      `A Presentation “${definition.id}” declara body.component e exige children.`,
+    );
+  }
+  if (actionBody !== null && children !== undefined) {
+    throw new Error(
+      `A Presentation “${definition.id}” usa body.action e não aceita children.`,
+    );
+  }
+  if (definition.assistant !== undefined && assistant === undefined) {
+    throw new Error(
+      `A Presentation “${definition.id}” declara assistência e exige a prop assistant.`,
+    );
+  }
+  if (definition.assistant === undefined && assistant !== undefined) {
+    throw new Error(
+      `A Presentation “${definition.id}” não declara assistência e não aceita a prop assistant.`,
+    );
+  }
+  const bodyInput =
+    actionBody === null
+      ? {}
+      : (resolvePresentationBindings(actionBody.input, context) as Record<
+          string,
+          unknown
+        >);
   const renderBody = (footerTarget: HTMLElement | null): ReactNode => {
+    if (actionBody === null) return children;
+    if (bodyAction === null) return null;
     if (bodyAction.kind === "form") {
       return (
         <ActionForm
           action={bodyAction as FormContract<Record<string, unknown>, unknown>}
           defaultValues={bodyInput}
-          submitLabel={definition.body.submitLabel}
+          submitLabel={actionBody.submitLabel}
           onCancel={invocation.surface === "page" ? undefined : closeSurface}
-          onSuccess={(data) => applyEffects(definition.body.onSuccess, data)}
+          onSuccess={(data) => applyEffects(actionBody.onSuccess, data)}
           disabled={hasSurfaceBlock}
           onLoadingChange={setBodyLoading}
           footer={(actions) =>
@@ -578,14 +693,14 @@ export function Presentation({
           input={bodyInput}
           state={listState}
           onStateChange={onListStateChange}
-          {...(definition.body.open === undefined
+          {...(actionBody.open === undefined
             ? {}
             : {
                 onRowClick: (item: Record<string, unknown>) =>
                   openTarget(
-                    definition.body.open!.presentation,
-                    definition.body.open!.surface,
-                    definition.body.open!.input,
+                    actionBody.open!.presentation,
+                    actionBody.open!.surface,
+                    actionBody.open!.input,
                     { ...context, item },
                   ),
               })}
@@ -593,7 +708,7 @@ export function Presentation({
       );
     }
     if (bodyAction.kind === "view") {
-      const fields = definition.body.fields ?? [];
+      const fields = actionBody.fields ?? [];
       return (
         <ActionView
           action={bodyAction as ViewContract<Record<string, unknown>, unknown>}
@@ -641,6 +756,22 @@ export function Presentation({
       <ArrowLeft aria-hidden />
     </Button>
   );
+  const assistantAction =
+    definition.assistant === undefined || assistantOpen ? undefined : (
+      <Button
+        size="icon"
+        variant="ghost"
+        aria-label={definition.assistant.triggerLabel}
+        title={definition.assistant.triggerLabel}
+        onClick={() => setAssistantOpen(true)}
+      >
+        {assistant?.icon ?? <MessageCircle aria-hidden />}
+      </Button>
+    );
+  const assistantPanel =
+    definition.assistant === undefined || assistant === undefined
+      ? undefined
+      : assistant.render({ close: () => setAssistantOpen(false) });
 
   return (
     <PresentationFrame
@@ -659,9 +790,17 @@ export function Presentation({
       }}
       className={className}
       bodyClassName={bodyClassNameProp}
-      hasBodyFooter={bodyAction.kind === "form"}
+      hasBodyFooter={bodyAction?.kind === "form"}
       blocked={surfaceBlocked}
-      listBody={bodyAction.kind === "list"}
+      listBody={bodyAction?.kind === "list"}
+      contentOwnsHeading={
+        !isPresentationActionBody(definition.body) &&
+        definition.body.heading === "content"
+      }
+      assistantOpen={assistantOpen}
+      assistantLabel={definition.assistant?.triggerLabel}
+      assistantAction={assistantAction}
+      assistantPanel={assistantPanel}
     >
       {renderBody}
     </PresentationFrame>

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

@@ -94,7 +94,7 @@ export function PaneBody({
   );
 }
 
-/** @deprecated Use PaneBody. Mantido durante a versão 12 para migração gradual. */
+/** @deprecated Use PaneBody. Alias mantido para migração; sai numa próxima versão major. */
 export function PaneContent({
   className,
   children,

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

@@ -48,6 +48,8 @@ export interface SplitProps {
   /** Chamado ao concluir uma mudança de layout; pode persistir o resultado em localStorage. */
   onLayoutChanged?: (layout: SplitLayout, meta: SplitLayoutChange) => void
   className?: string
+  /** Identificador semântico opcional para testes e composição de patterns. */
+  'data-slot'?: string
   children: ReactNode
 }
 
@@ -86,6 +88,7 @@ export function Split({
   defaultLayout,
   onLayoutChanged,
   className,
+  'data-slot': dataSlot = 'split',
   children,
 }: SplitProps): React.ReactElement {
   const panes = panesOf(children)
@@ -93,7 +96,7 @@ export function Split({
 
   if (!resizable) {
     return (
-      <div id={id === undefined ? undefined : String(id)} data-slot="split" data-direction={direction} className={cn('flex min-h-0 min-w-0 flex-1', vertical && 'flex-col', className)}>
+      <div id={id === undefined ? undefined : String(id)} data-slot={dataSlot} data-direction={direction} className={cn('flex min-h-0 min-w-0 flex-1', vertical && 'flex-col', className)}>
         {panes}
       </div>
     )
@@ -111,7 +114,7 @@ export function Split({
       orientation={direction}
       defaultLayout={defaultLayout}
       onLayoutChanged={onLayoutChanged}
-      data-slot="split"
+      data-slot={dataSlot}
       className={cn('min-h-0 min-w-0 flex-1', className)}
     >
       {panes.flatMap((pane, index) => {

package/src/ui/components/patterns/surface-assistant.tsx

@@ -0,0 +1,74 @@
+import type { ReactNode } from "react";
+import { cn } from "../../lib/cn.ts";
+import { Pane, type PaneSize, Split } from "./split.tsx";
+
+export interface SurfaceAssistantProps {
+  /** Controla somente a presença visual do painel; o conteúdo pertence ao consumidor. */
+  open: boolean;
+  /** Nome acessível da região complementar. */
+  assistantLabel: string;
+  /** Conteúdo principal que permanece visível à esquerda. */
+  children: ReactNode;
+  /** Painel fornecido pela superfície que conhece o contexto do recurso. */
+  assistant: ReactNode;
+  initialSize?: PaneSize;
+  minSize?: PaneSize;
+  maxSize?: PaneSize;
+  className?: string;
+  contentClassName?: string;
+  assistantClassName?: string;
+}
+
+/**
+ * Mantém conteúdo e assistência contextual na mesma superfície. O host decide abertura,
+ * trigger e dados; o pattern preserva a relação espacial e o redimensionamento.
+ */
+export function SurfaceAssistant({
+  open,
+  assistantLabel,
+  children,
+  assistant,
+  initialSize = "28rem",
+  minSize = "20rem",
+  maxSize = "40rem",
+  className,
+  contentClassName,
+  assistantClassName,
+}: SurfaceAssistantProps): React.ReactElement {
+  return (
+    <Split
+      resizable
+      data-slot="surface-assistant"
+      className={cn("h-full", className)}
+    >
+      <Pane
+        key="surface-content"
+        id="surface-content"
+        grow
+        inset="none"
+        className={cn("h-full", contentClassName)}
+      >
+        {children}
+      </Pane>
+      {open ? (
+        <Pane
+          key="surface-assistant"
+          id="surface-assistant"
+          initialSize={initialSize}
+          minSize={minSize}
+          maxSize={maxSize}
+          inset="none"
+          className={cn("h-full bg-background", assistantClassName)}
+        >
+          <aside
+            data-slot="surface-assistant-panel"
+            aria-label={assistantLabel}
+            className="h-full min-w-0 overflow-hidden"
+          >
+            {assistant}
+          </aside>
+        </Pane>
+      ) : null}
+    </Split>
+  );
+}

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

@@ -101,7 +101,7 @@ export function CardBody({
   );
 }
 
-/** @deprecated Use CardBody. Mantido durante a versão 12 para migração gradual. */
+/** @deprecated Use CardBody. Alias mantido para migração; sai numa próxima versão major. */
 export function CardContent({
   className,
   ...props

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

@@ -8,11 +8,11 @@ export type DetailGroupOrientation = 'vertical' | 'horizontal'
 export type DetailGroupColumns = 1 | 2 | 3 | 4 | 'auto'
 
 export interface DetailGroupProps extends React.ComponentProps<'dl'> {
-  /** `framed` aplica a superfície e a moldura canônicas ao conjunto. */
+  /** `framed` aplica a moldura canônica ao conjunto; na orientação horizontal, a coluna de rótulos ganha fundo sutil. */
   variant?: DetailGroupVariant
   /** Exibe hairlines somente entre os campos, sem exigir moldura externa. */
   dividers?: boolean
-  /** Número responsivo de colunas ou distribuição automática por largura mínima. */
+  /** Número fixo de colunas ou distribuição automática por largura mínima. */
   columns?: DetailGroupColumns
   /** Organiza a chave sobre o valor ou ao lado dele em cada campo. */
   orientation?: DetailGroupOrientation
@@ -59,13 +59,13 @@ function DetailGroup({
             '[&>[data-slot=detail-field]]:p-3',
           variant === 'framed' &&
             'overflow-hidden rounded-lg border border-border bg-transparent text-foreground',
+          // Default da coluna de rótulos como CLASSE, antes do `className`: assim uma classe do
+          // consumidor (`[--detail-label-width:9rem]`) a substitui. Em `style` inline, o default
+          // vencia qualquer classe e só `style` conseguia ajustar a largura.
+          splitHorizontalField && '[--detail-label-width:8.5rem]',
           className,
         )}
-        style={
-          splitHorizontalField
-            ? ({ '--detail-label-width': '8.5rem', ...style } as React.CSSProperties)
-            : style
-        }
+        style={style}
         {...props}
       >
         {children}

package/src/ui/components/primitives/radio-group.tsx

@@ -25,7 +25,7 @@ function RadioGroupItem({
     <RadioGroupPrimitive.Item
       data-slot="radio-group-item"
       className={cn(
-        "aspect-square size-4 shrink-0 rounded-full border border-input text-primary transition-[color,box-shadow] outline-none focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 dark:bg-input/30 dark:aria-invalid:ring-context-danger/40",
+        "peer aspect-square size-4 shrink-0 rounded-full border border-input text-primary transition-[color,box-shadow] outline-none focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-context-danger aria-invalid:ring-context-danger/20 dark:bg-input/30 dark:aria-invalid:ring-context-danger/40",
         className
       )}
       {...props}

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

@@ -92,7 +92,7 @@ interface SelectCustomBase extends SelectBaseProps {
   clearable?: boolean
   /** `outline`: compacto com borda; `ghost`: compacto sem borda nem fundo. */
   variant?: 'default' | 'outline' | 'ghost'
-  /** Placeholder enquanto se digita a busca (cai pro `placeholder`). */
+  /** Placeholder da linha de busca dentro da lista. Default: `'Buscar…'`. */
   searchPlaceholder?: string
   emptyText?: string
   /** Ação custom no FIM do campo, dentro do controle (antes do chevron) — ex.: um botão que

package/src/ui/docs/content/action-form-dialog.md

@@ -3,8 +3,11 @@
 Use `ActionFormDialog` quando o formulário precisar interromper o fluxo atual sem levar a pessoa
 para outra página. O consumidor controla `open`; depois de uma execução bem-sucedida, o componente
 fecha o modal. O cabeçalho e o rodapé permanecem visíveis enquanto os campos podem rolar.
-Quando há cancelamento, o rodapé usa um `ButtonGroup` dividido: `Cancelar` aparece em `outline` e
-a ação principal permanece `solid`, ambas no tamanho normal de uma decisão modal.
+O rodapé agrupa as decisões em um `ButtonGroup` cuja largura acompanha o conteúdo: `Cancelar`
+aparece em `ghost` e a ação principal permanece `solid`, ambas no tamanho normal de uma decisão
+modal. `Cancelar` está sempre presente; sem `onCancel` próprio, ele fecha o modal.
+Com `footerDistribution="equal"`, as duas decisões dividem a faixa e `Cancelar` passa a `outline`,
+salvo escolha explícita em `cancelVariant`.
 
 ```tsx preview
 const [open, setOpen] = useState(false);
@@ -26,8 +29,12 @@ render(
 
 | Propriedade           | Tipo                                              | Padrão     | Descrição                                                                                                                                                                   |
 | --------------------- | ------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `open / onOpenChange` | `boolean / (open: boolean) => void`               |            | Estado controlado do modal. `onOpenChange(false)` é chamado no sucesso e ao cancelar.                                                                                       |
+| `open / onOpenChange` | `boolean / (open: boolean) => void`               |            | Estado controlado do modal. `onOpenChange(false)` é chamado no sucesso e, quando não há `onCancel` próprio, ao cancelar.                                                                                       |
 | `title`               | `string`                                          |            | Nome da tarefa exibido no cabeçalho.                                                                                                                                        |
 | `intro`               | `ReactNode`                                       |            | Contexto relevante no início do corpo, como texto ou `Alert`.                                                                                                               |
 | `submitLabel`         | `string`                                          | `'Salvar'` | Resultado da ação principal. Preserve o padrão em criação e edição comuns; sobrescreva apenas quando a operação tiver outro efeito, como `Renomear` ou `Criar nova versão`. |
-| `…ActionFormProps`    | `action, defaultValues, onSuccess, fieldOptions…` |            | Demais propriedades repassadas ao `ActionForm` interno.                                                                                                                     |
+| `footerDistribution`  | `'content' \| 'equal'`                            | `'content'` | Mantém a largura das ações pelo conteúdo ou divide a faixa igualmente. |
+| `cancelVariant`       | `'ghost' \| 'outline'`                            | `'ghost'`; `'outline'` com `equal` | Tratamento do `Cancelar`. O valor explícito vence o default derivado de `footerDistribution`. |
+| `onCancel`            | `() => void`                                      | fecha o modal | Substitui o fechamento padrão do `Cancelar`; nesse caso, o consumidor decide quando chamar `onOpenChange(false)`. |
+| `onSuccess`           | `(data: TData) => void`                           |            | Executado depois do sucesso, antes de o componente fechar o modal. |
+| `…ActionFormProps`    | `action, defaultValues, fieldOptions…`            |            | Demais propriedades repassadas ao `ActionForm` interno. `className`, `body` e `footer` não são repassadas: o wrapper as substitui para montar o corpo rolável e o footer do modal. |