@softize/opus 17.2.0 → 18.0.0

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

@@ -17,49 +17,69 @@
  * inline; toast em sucesso/erro. Emite `data-action="<action.name>"` na raiz (selector E2E).
  */
 
-import { createContext, useContext, useEffect, useId } from 'react'
-import type { UseFormReturn } from 'react-hook-form'
+import { createContext, useContext, useEffect, useId } from "react";
+import type { UseFormReturn } from "react-hook-form";
 import {
   getLogicalType,
   type FieldWidget,
   type FormContract,
   type OptionsSpec,
-} from '../../../core/index.ts'
-import { useDicts, useFormAction, type DictLike } from '../../drivers/react.tsx'
-import { z, type ZodTypeAny } from 'zod'
-import { cn } from '../../lib/cn.ts'
-import { humanizeActionError } from '../../lib/action-errors.ts'
-import { objectSchemaShape } from '../../lib/object-schema.ts'
-import { toast } from '../primitives/sonner.tsx'
-import { Button } from '../primitives/button.tsx'
-import { Input } from '../primitives/input.tsx'
-import { Textarea } from '../primitives/textarea.tsx'
-import { Checkbox } from '../primitives/checkbox.tsx'
-import { IconPicker } from '../primitives/icon-picker.tsx'
-import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } 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 { Field, FieldError, FieldGroup, FieldLabel } from '../primitives/field.tsx'
+} from "../../../core/index.ts";
+import {
+  useDicts,
+  useFormAction,
+  type DictLike,
+} from "../../drivers/react.tsx";
+import { z, type ZodTypeAny } from "zod";
+import { cn } from "../../lib/cn.ts";
+import { humanizeActionError } from "../../lib/action-errors.ts";
+import { objectSchemaShape } from "../../lib/object-schema.ts";
+import { toast } from "../primitives/sonner.tsx";
+import { Button, type ButtonVariant } from "../primitives/button.tsx";
+import { ButtonGroup } from "../primitives/button-group.tsx";
+import { Input } from "../primitives/input.tsx";
+import { Textarea } from "../primitives/textarea.tsx";
+import { Checkbox } from "../primitives/checkbox.tsx";
+import { IconPicker } from "../primitives/icon-picker.tsx";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} 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 {
+  Field,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+} from "../primitives/field.tsx";
 
 // =============================================================================
 // Inferência de tipo de field a partir do Zod schema
 // =============================================================================
 
 type FieldKind =
-  | { kind: 'text'; required: boolean }
-  | { kind: 'textarea'; required: boolean }
-  | { kind: 'checkbox'; required: boolean }
-  | { kind: 'select'; required: boolean; options: string[] }
-  | { kind: 'multiselect'; required: boolean; options: string[] }
-  | { kind: 'toggle-group'; required: boolean; multiple: boolean; options: string[] }
-  | { kind: 'lines'; required: boolean }
-  | { kind: 'refItems'; required: boolean }
-  | { kind: 'icon'; required: boolean }
+  | { kind: "text"; required: boolean }
+  | { kind: "textarea"; required: boolean }
+  | { kind: "checkbox"; required: boolean }
+  | { kind: "select"; required: boolean; options: string[] }
+  | { kind: "multiselect"; required: boolean; options: string[] }
+  | {
+      kind: "toggle-group";
+      required: boolean;
+      multiple: boolean;
+      options: string[];
+    }
+  | { kind: "lines"; required: boolean }
+  | { kind: "refItems"; required: boolean }
+  | { kind: "icon"; required: boolean };
 
 function unwrap(schema: ZodTypeAny): { inner: ZodTypeAny; required: boolean } {
-  let inner: ZodTypeAny = schema
-  let required = true
+  let inner: ZodTypeAny = schema;
+  let required = true;
   // ZodOptional / ZodDefault / ZodNullable → desce no _def.innerType.
   while (
     inner instanceof z.ZodOptional ||
@@ -67,42 +87,46 @@ function unwrap(schema: ZodTypeAny): { inner: ZodTypeAny; required: boolean } {
     inner instanceof z.ZodNullable
   ) {
     if (inner instanceof z.ZodOptional || inner instanceof z.ZodDefault) {
-      required = false
+      required = false;
     }
-    const def = (inner as unknown as { _def: { innerType: ZodTypeAny } })._def
-    inner = def.innerType
+    const def = (inner as unknown as { _def: { innerType: ZodTypeAny } })._def;
+    inner = def.innerType;
   }
-  return { inner, required }
+  return { inner, required };
 }
 
 function inferFieldKind(schema: ZodTypeAny): FieldKind {
-  const { inner, required } = unwrap(schema)
+  const { inner, required } = unwrap(schema);
 
   if (inner instanceof z.ZodBoolean) {
-    return { kind: 'checkbox', required }
+    return { kind: "checkbox", required };
   }
 
   if (inner instanceof z.ZodEnum) {
-    return { kind: 'select', required, options: inner.options as string[] }
+    return { kind: "select", required, options: inner.options as string[] };
   }
 
   // z.array(...) → multiselect (Select multiple). Opções estáticas só quando o elemento é
   // z.enum; pra z.array(z.string()) (ids em runtime) as opções vêm de fora (spec).
   if (inner instanceof z.ZodArray) {
-    const el = (inner._def as { type: ZodTypeAny }).type
-    return { kind: 'multiselect', required, options: el instanceof z.ZodEnum ? (el.options as string[]) : [] }
+    const el = (inner._def as { type: ZodTypeAny }).type;
+    return {
+      kind: "multiselect",
+      required,
+      options: el instanceof z.ZodEnum ? (el.options as string[]) : [],
+    };
   }
 
   if (inner instanceof z.ZodString) {
     const maxCheck = inner._def.checks.find(
-      (c: { kind: string }) => c.kind === 'max',
-    ) as { value: number } | undefined
+      (c: { kind: string }) => c.kind === "max",
+    ) as { value: number } | undefined;
     if (maxCheck !== undefined && maxCheck.value > 200) {
-      return { kind: 'textarea', required }
+      return { kind: "textarea", required };
     }
   }
 
-  return { kind: 'text', required }
+  return { kind: "text", required };
 }
 
 // =============================================================================
@@ -110,10 +134,10 @@ function inferFieldKind(schema: ZodTypeAny): FieldKind {
 // =============================================================================
 
 interface FieldSpec {
-  label?: string
-  placeholder?: string
+  label?: string;
+  placeholder?: string;
   /** Ajuda na label: ícone ⓘ + tooltip no hover. */
-  help?: string
+  help?: string;
   /** Override explícito do tipo de campo, quando o auto-detect do Zod não basta.
    *  Honra 'textarea' (string sem max), 'code' (textarea monoespaçada, ex.: SKILL.md),
    *  'lines' (z.array(z.string()) num textarea, um item por linha), 'refItems'
@@ -121,13 +145,13 @@ interface FieldSpec {
    *  `ref` vêm de fieldOptions[campo]) e 'icon' (string com o nome kebab-case da
    *  paleta da casa — renderiza o <IconPicker>) e 'toggle-group' para escolhas
    *  declarativas com opções ricas. */
-  widget?: FieldWidget
+  widget?: FieldWidget;
   /** Renderiza o campo só quando true pro input atual (ex.: clientId só se !staff).
    *  No modo COMPOSIÇÃO o condicional pode (e deve) ser JSX de quem diagrama. */
-  showWhen?: (input: Record<string, unknown>) => boolean
+  showWhen?: (input: Record<string, unknown>) => boolean;
   /** Origem declarada das opções (static/dictionary/lookup) — ver a precedência
    *  em `ActionFormField`. `dictionary` resolve pelos dicts do OpusProvider. */
-  options?: OptionsSpec
+  options?: OptionsSpec;
 }
 
 /** Opções declaradas no FieldSpec: static direto; dictionary via provider; lookup
@@ -136,39 +160,42 @@ function optionsFromSpec(
   spec: OptionsSpec | undefined,
   dicts: Record<string, DictLike>,
 ): SelectOption[] | undefined {
-  if (spec === undefined) return undefined
-  if (spec.kind === 'static') {
+  if (spec === undefined) return undefined;
+  if (spec.kind === "static") {
     return spec.items.map((i) => ({
       value: i.value,
-      label: typeof i.label === 'string' ? i.label : i.label.default,
-    }))
+      label: typeof i.label === "string" ? i.label : i.label.default,
+    }));
   }
-  if (spec.kind === 'dictionary') {
-    const dict = dicts[spec.ref]
-    if (dict === undefined) return undefined
-    return dict.options().map((o) => ({ value: o.value, label: o.label }))
+  if (spec.kind === "dictionary") {
+    const dict = dicts[spec.ref];
+    if (dict === undefined) return undefined;
+    return dict.options().map((o) => ({ value: o.value, label: o.label }));
   }
-  return undefined
+  return undefined;
 }
 
 /** Fallback zero-config: o schema do contrato CARREGA o vocabulário do `t.dict`
  *  (meta `params.keys/entries`) — labels sem registry no provider. Cobre o campo
  *  dict e o multiselect com elemento dict. */
 function dictMetaOptions(schema: ZodTypeAny): SelectOption[] | undefined {
-  const { inner } = unwrap(schema)
-  const el = inner instanceof z.ZodArray ? (inner._def as { type: ZodTypeAny }).type : inner
-  const meta = getLogicalType(el as object)
-  if (meta?.logicalType !== 'dict') return undefined
+  const { inner } = unwrap(schema);
+  const el =
+    inner instanceof z.ZodArray
+      ? (inner._def as { type: ZodTypeAny }).type
+      : inner;
+  const meta = getLogicalType(el as object);
+  if (meta?.logicalType !== "dict") return undefined;
   const params = (meta.params ?? {}) as {
-    keys?: unknown
-    entries?: Record<string, { label?: unknown }>
-  }
-  const { keys, entries } = params
-  if (!Array.isArray(keys) || entries === undefined) return undefined
+    keys?: unknown;
+    entries?: Record<string, { label?: unknown }>;
+  };
+  const { keys, entries } = params;
+  if (!Array.isArray(keys) || entries === undefined) return undefined;
   return (keys as string[]).map((k) => {
-    const label = entries[k]?.label
-    return { value: k, label: typeof label === 'string' ? label : k }
-  })
+    const label = entries[k]?.label;
+    return { value: k, label: typeof label === "string" ? label : k };
+  });
 }
 
 /**
@@ -182,8 +209,12 @@ function dictMetaOptions(schema: ZodTypeAny): SelectOption[] | undefined {
  * o tooltip vem aberto); abre só no hover. preventDefault: clicar o ícone não dispara o label
  * (não foca o input / não toggla).
  */
-export function LabelHelp({ help }: { help: string | undefined }): React.ReactElement | null {
-  if (help === undefined || help.trim().length === 0) return null
+export function LabelHelp({
+  help,
+}: {
+  help: string | undefined;
+}): React.ReactElement | null {
+  if (help === undefined || help.trim().length === 0) return null;
   return (
     <TooltipProvider delayDuration={300}>
       <Tooltip>
@@ -194,8 +225,8 @@ export function LabelHelp({ help }: { help: string | undefined }): React.ReactEl
             aria-label="Ajuda"
             onClick={(e) => {
               // Clicar o ícone não ativa o label (não foca/toggla o campo).
-              e.preventDefault()
-              e.stopPropagation()
+              e.preventDefault();
+              e.stopPropagation();
             }}
             className="inline-flex shrink-0 cursor-help text-muted-foreground/50 transition-colors hover:text-muted-foreground"
           >
@@ -207,12 +238,16 @@ export function LabelHelp({ help }: { help: string | undefined }): React.ReactEl
         <TooltipContent>{help}</TooltipContent>
       </Tooltip>
     </TooltipProvider>
-  )
+  );
 }
 
 /** Marca de obrigatório na label — derivada do Zod (campo sem optional/default). */
-function RequiredMark({ required }: { required: boolean }): React.ReactElement | null {
-  if (!required) return null
+function RequiredMark({
+  required,
+}: {
+  required: boolean;
+}): React.ReactElement | null {
+  if (!required) return null;
   return (
     <>
       <span aria-hidden className="ml-0.5 text-context-danger-emphasis">
@@ -220,17 +255,17 @@ function RequiredMark({ required }: { required: boolean }): React.ReactElement |
       </span>
       <span className="sr-only"> (obrigatório)</span>
     </>
-  )
+  );
 }
 
 /** action.messages.* pode ser string ou I18nRef ({ key, default }). Resolve pra texto. */
 function msgText(m: unknown, fallback: string): string {
-  if (typeof m === 'string') return m
-  if (m !== null && typeof m === 'object' && 'default' in m) {
-    const d = (m as { default: unknown }).default
-    if (typeof d === 'string') return d
+  if (typeof m === "string") return m;
+  if (m !== null && typeof m === "object" && "default" in m) {
+    const d = (m as { default: unknown }).default;
+    if (typeof d === "string") return d;
   }
-  return fallback
+  return fallback;
 }
 
 // =============================================================================
@@ -239,13 +274,13 @@ function msgText(m: unknown, fallback: string): string {
 
 export interface ActionFormContextValue {
   /** RHF do useFormAction. O shape é dinâmico — os paths entram como string. */
-  form: UseFormReturn<Record<string, unknown>>
-  shape: Record<string, ZodTypeAny | undefined>
-  fields: Record<string, FieldSpec>
-  fieldOptions?: Record<string, SelectOption[]> | undefined
+  form: UseFormReturn<Record<string, unknown>>;
+  shape: Record<string, ZodTypeAny | undefined>;
+  fields: Record<string, FieldSpec>;
+  fieldOptions?: Record<string, SelectOption[]> | undefined;
 }
 
-const ActionFormContext = createContext<ActionFormContextValue | null>(null)
+const ActionFormContext = createContext<ActionFormContextValue | null>(null);
 
 /**
  * O contexto do `<ActionForm>` pai — a válvula de escape pra CONTROLE CUSTOM no
@@ -256,9 +291,12 @@ const ActionFormContext = createContext<ActionFormContextValue | null>(null)
  * zod-resolver, erro inline e submit continuam do contrato.
  */
 export function useActionFormContext(): ActionFormContextValue {
-  const ctx = useContext(ActionFormContext)
-  if (ctx === null) throw new Error('useActionFormContext precisa estar dentro de um <ActionForm>.')
-  return ctx
+  const ctx = useContext(ActionFormContext);
+  if (ctx === null)
+    throw new Error(
+      "useActionFormContext precisa estar dentro de um <ActionForm>.",
+    );
+  return ctx;
 }
 
 // =============================================================================
@@ -267,95 +305,109 @@ export function useActionFormContext(): ActionFormContextValue {
 
 export interface ActionFormFieldProps {
   /** Nome do campo no input do contrato (a chave em `fields`/schema). */
-  name: string
+  name: string;
   /** Opções por id de runtime — sobrepõe o fieldOptions do form e o z.enum. */
-  options?: SelectOption[]
+  options?: SelectOption[];
   /** Classes do invólucro do campo (ex.: col-span-2 numa grid). */
-  className?: string
+  className?: string;
 }
 
-export function ActionFormField({ name, options: optionsProp, className }: ActionFormFieldProps): React.ReactElement | null {
-  const ctx = useContext(ActionFormContext)
-  if (ctx === null) throw new Error('ActionFormField precisa estar dentro de um <ActionForm>.')
-  const dicts = useDicts()
-  const { form, shape, fields, fieldOptions } = ctx
+export function ActionFormField({
+  name,
+  options: optionsProp,
+  className,
+}: ActionFormFieldProps): React.ReactElement | null {
+  const ctx = useContext(ActionFormContext);
+  if (ctx === null)
+    throw new Error("ActionFormField precisa estar dentro de um <ActionForm>.");
+  const dicts = useDicts();
+  const { form, shape, fields, fieldOptions } = ctx;
   // Assina TODOS os valores: alimenta o showWhen e os widgets controlados.
-  const formValues = form.watch()
+  const formValues = form.watch();
 
   const focusControl = (): void => {
-    const control = document.getElementById(name)
-    if (control?.dataset.slot === 'toggle-group') {
-      control.querySelector<HTMLElement>('[data-slot="toggle-group-item"]:not([disabled])')?.focus()
-      return
+    const control = document.getElementById(name);
+    if (control?.dataset.slot === "toggle-group") {
+      control
+        .querySelector<HTMLElement>(
+          '[data-slot="toggle-group-item"]:not([disabled])',
+        )
+        ?.focus();
+      return;
     }
-    control?.focus()
-  }
-
-  const spec: FieldSpec = fields[name] ?? {}
-  const fieldError = form.formState.errors[name]
-  const errorMessage = typeof fieldError?.message === 'string' ? fieldError.message : undefined
-  const errorId = errorMessage !== undefined ? `${name}-error` : undefined
-  const describedBy = errorId
+    control?.focus();
+  };
+
+  const spec: FieldSpec = fields[name] ?? {};
+  const fieldError = form.formState.errors[name];
+  const errorMessage =
+    typeof fieldError?.message === "string" ? fieldError.message : undefined;
+  const errorId = errorMessage !== undefined ? `${name}-error` : undefined;
+  const describedBy = errorId;
   useEffect(() => {
-    if (errorMessage === undefined) return
-    const control = document.getElementById(name)
+    if (errorMessage === undefined) return;
+    const control = document.getElementById(name);
     const firstInvalidToggle = control
-      ?.closest('form')
-      ?.querySelector<HTMLElement>('[data-slot="toggle-group"][aria-invalid="true"]')
-    if (firstInvalidToggle?.id === name) focusControl()
-  }, [errorMessage, name])
-
-  const fieldSchema = shape[name]
-  if (fieldSchema === undefined) return null
-  if (typeof spec.showWhen === 'function' && !spec.showWhen(formValues)) return null
-
-  const inferred = inferFieldKind(fieldSchema)
+      ?.closest("form")
+      ?.querySelector<HTMLElement>(
+        '[data-slot="toggle-group"][aria-invalid="true"]',
+      );
+    if (firstInvalidToggle?.id === name) focusControl();
+  }, [errorMessage, name]);
+
+  const fieldSchema = shape[name];
+  if (fieldSchema === undefined) return null;
+  if (typeof spec.showWhen === "function" && !spec.showWhen(formValues))
+    return null;
+
+  const inferred = inferFieldKind(fieldSchema);
   // `widget` no FieldSpec sobrepõe o auto-detect (ex.: textarea pra string sem max).
   const fieldKind: FieldKind =
-    spec.widget === 'textarea' || spec.widget === 'code'
-      ? { kind: 'textarea', required: inferred.required }
-      : spec.widget === 'lines'
-        ? { kind: 'lines', required: inferred.required }
-        : spec.widget === 'refItems'
-          ? { kind: 'refItems', required: inferred.required }
-          : spec.widget === 'icon'
-            ? { kind: 'icon', required: inferred.required }
-            : spec.widget === 'toggle-group'
+    spec.widget === "textarea" || spec.widget === "code"
+      ? { kind: "textarea", required: inferred.required }
+      : spec.widget === "lines"
+        ? { kind: "lines", required: inferred.required }
+        : spec.widget === "refItems"
+          ? { kind: "refItems", required: inferred.required }
+          : spec.widget === "icon"
+            ? { kind: "icon", required: inferred.required }
+            : spec.widget === "toggle-group"
               ? {
-                  kind: 'toggle-group',
+                  kind: "toggle-group",
                   required: inferred.required,
-                  multiple: inferred.kind === 'multiselect',
+                  multiple: inferred.kind === "multiselect",
                   options:
-                    inferred.kind === 'select' || inferred.kind === 'multiselect'
+                    inferred.kind === "select" ||
+                    inferred.kind === "multiselect"
                       ? inferred.options
                       : [],
                 }
-              : inferred
+              : inferred;
   // Precedência das opções: prop do campo > fieldOptions do form > spec.options
   // (dictionary via provider, static direto) > meta do t.dict no schema
   // (zero-config) > chaves cruas do z.enum.
-  const runtimeOptions = optionsProp ?? fieldOptions?.[name]
-  const specOptions = optionsFromSpec(spec.options, dicts)
-  const declaredOptions = runtimeOptions ?? specOptions
+  const runtimeOptions = optionsProp ?? fieldOptions?.[name];
+  const specOptions = optionsFromSpec(spec.options, dicts);
+  const declaredOptions = runtimeOptions ?? specOptions;
   const options: SelectOption[] =
     declaredOptions ??
     dictMetaOptions(fieldSchema) ??
-    (fieldKind.kind === 'select' ||
-    fieldKind.kind === 'multiselect' ||
-    fieldKind.kind === 'toggle-group'
+    (fieldKind.kind === "select" ||
+    fieldKind.kind === "multiselect" ||
+    fieldKind.kind === "toggle-group"
       ? fieldKind.options.map((o) => ({ value: o, label: o }))
-      : [])
+      : []);
   // Campo texto COM opções declaradas (runtime ou spec) → single-select por-id.
   const effectiveKind: FieldKind =
-    fieldKind.kind === 'text' && declaredOptions !== undefined
-      ? { kind: 'select', required: fieldKind.required, options: [] }
-      : fieldKind
+    fieldKind.kind === "text" && declaredOptions !== undefined
+      ? { kind: "select", required: fieldKind.required, options: [] }
+      : fieldKind;
 
   const setValue = (v: unknown): void =>
-    form.setValue(name, v, { shouldValidate: true, shouldDirty: true })
+    form.setValue(name, v, { shouldValidate: true, shouldDirty: true });
 
   // Checkbox tem layout próprio (controle + label na mesma linha).
-  if (fieldKind.kind === 'checkbox') {
+  if (fieldKind.kind === "checkbox") {
     return (
       <Field
         className={className}
@@ -377,9 +429,11 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
           </span>
           <LabelHelp help={spec.help} />
         </FieldLabel>
-        {errorMessage !== undefined && <FieldError id={errorId}>{errorMessage}</FieldError>}
+        {errorMessage !== undefined && (
+          <FieldError id={errorId}>{errorMessage}</FieldError>
+        )}
       </Field>
-    )
+    );
   }
 
   return (
@@ -389,7 +443,12 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
       aria-invalid={errorMessage !== undefined}
       aria-describedby={describedBy}
     >
-      <FieldLabel id={`${name}-label`} htmlFor={name} onClick={focusControl} className="items-center gap-1.5">
+      <FieldLabel
+        id={`${name}-label`}
+        htmlFor={name}
+        onClick={focusControl}
+        className="items-center gap-1.5"
+      >
         <span>
           {spec.label ?? name}
           <RequiredMark required={fieldKind.required} />
@@ -397,7 +456,7 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
         <LabelHelp help={spec.help} />
       </FieldLabel>
 
-      {effectiveKind.kind === 'toggle-group' ? (
+      {effectiveKind.kind === "toggle-group" ? (
         effectiveKind.multiple ? (
           <ToggleGroup
             type="multiple"
@@ -420,7 +479,9 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
                 className="h-auto min-h-14 w-full cursor-pointer justify-start whitespace-normal p-3 text-left data-[state=on]:border-primary data-[state=on]:bg-primary/5 data-[state=on]:shadow-sm"
               >
                 <span className="min-w-0">
-                  <span className="block">{option.content ?? option.label}</span>
+                  <span className="block">
+                    {option.content ?? option.label}
+                  </span>
                   {option.hint !== undefined && (
                     <span className="mt-1 block text-xs font-normal text-muted-foreground">
                       {option.hint}
@@ -434,10 +495,10 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
           <ToggleGroup
             type="single"
             id={name}
-            value={(formValues[name] as string | undefined) ?? ''}
+            value={(formValues[name] as string | undefined) ?? ""}
             onValueChange={(value) => {
-              if (value !== '' || !effectiveKind.required) {
-                setValue(value === '' ? undefined : value)
+              if (value !== "" || !effectiveKind.required) {
+                setValue(value === "" ? undefined : value);
               }
             }}
             variant="outline"
@@ -457,7 +518,9 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
                 className="h-auto min-h-14 w-full cursor-pointer justify-start whitespace-normal p-3 text-left data-[state=on]:border-primary data-[state=on]:bg-primary/5 data-[state=on]:shadow-sm"
               >
                 <span className="min-w-0">
-                  <span className="block">{option.content ?? option.label}</span>
+                  <span className="block">
+                    {option.content ?? option.label}
+                  </span>
                   {option.hint !== undefined && (
                     <span className="mt-1 block text-xs font-normal text-muted-foreground">
                       {option.hint}
@@ -468,7 +531,7 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
             ))}
           </ToggleGroup>
         )
-      ) : effectiveKind.kind === 'multiselect' ? (
+      ) : effectiveKind.kind === "multiselect" ? (
         <Select
           multiple
           searchable
@@ -476,16 +539,16 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
           value={(formValues[name] as string[] | undefined) ?? []}
           onChange={(v) => setValue(v)}
           options={options}
-          placeholder={spec.placeholder ?? 'Selecione…'}
+          placeholder={spec.placeholder ?? "Selecione…"}
           className="w-full"
           aria-invalid={errorMessage !== undefined}
           aria-describedby={describedBy}
         />
-      ) : effectiveKind.kind === 'select' ? (
+      ) : effectiveKind.kind === "select" ? (
         // w-full: campo de FORM alinha com os inputs (todos cheios) — coluna uniforme.
         <Select
           id={name}
-          value={(formValues[name] as string | undefined) ?? ''}
+          value={(formValues[name] as string | undefined) ?? ""}
           onChange={(v) => setValue(v)}
           options={options}
           // A régua do próprio Select: lista curta e conhecida se percorre com o olho;
@@ -494,30 +557,33 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
           // saber se o dicionário dele cresceu. (Veio de patch da Grand Brasil; subiu em
           // 8.6.9 porque patch local morre calado a cada bump.)
           searchable={options.length > 6}
-          placeholder={spec.placeholder ?? 'Selecione…'}
+          placeholder={spec.placeholder ?? "Selecione…"}
           className="w-full"
           aria-invalid={errorMessage !== undefined}
           aria-describedby={describedBy}
         />
-      ) : effectiveKind.kind === 'lines' ? (
+      ) : effectiveKind.kind === "lines" ? (
         // Lista de strings num textarea: um item por linha. split/join round-trip
         // estável (linhas vazias do meio da digitação são filtradas no servidor).
         <Textarea
           id={name}
-          placeholder={spec.placeholder ?? ''}
+          placeholder={spec.placeholder ?? ""}
           rows={4}
           className="max-h-80"
-          value={((formValues[name] as string[] | undefined) ?? []).join('\n')}
-          onChange={(e) => setValue(e.target.value.split('\n'))}
+          value={((formValues[name] as string[] | undefined) ?? []).join("\n")}
+          onChange={(e) => setValue(e.target.value.split("\n"))}
           aria-invalid={errorMessage !== undefined}
           aria-describedby={describedBy}
         />
-      ) : effectiveKind.kind === 'refItems' ? (
+      ) : effectiveKind.kind === "refItems" ? (
         // Lista composta {ref, text}: cada linha = select de referência (opções de
         // fieldOptions) + texto. Estruturado de propósito — o ref nunca é texto livre.
         (() => {
-          const items = (formValues[name] as Array<{ ref: string; text: string }> | undefined) ?? []
-          const setItems = (next: Array<{ ref: string; text: string }>): void => setValue(next)
+          const items =
+            (formValues[name] as
+              Array<{ ref: string; text: string }> | undefined) ?? [];
+          const setItems = (next: Array<{ ref: string; text: string }>): void =>
+            setValue(next);
           return (
             <div className="space-y-2">
               {items.map((item, i) => (
@@ -525,7 +591,13 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
                   <Select
                     id={i === 0 ? name : `${name}-${i}-ref`}
                     value={item.ref}
-                    onChange={(v) => setItems(items.map((it, j) => (j === i ? { ...it, ref: v } : it)))}
+                    onChange={(v) =>
+                      setItems(
+                        items.map((it, j) =>
+                          j === i ? { ...it, ref: v } : it,
+                        ),
+                      )
+                    }
                     options={options}
                     placeholder="Papel…"
                     className="w-44 shrink-0"
@@ -535,8 +607,14 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
                   <Input
                     id={`${name}-${i}-text`}
                     value={item.text}
-                    placeholder={spec.placeholder ?? 'Descreva o critério…'}
-                    onChange={(e) => setItems(items.map((it, j) => (j === i ? { ...it, text: e.target.value } : it)))}
+                    placeholder={spec.placeholder ?? "Descreva o critério…"}
+                    onChange={(e) =>
+                      setItems(
+                        items.map((it, j) =>
+                          j === i ? { ...it, text: e.target.value } : it,
+                        ),
+                      )
+                    }
                     aria-invalid={errorMessage !== undefined}
                     aria-describedby={describedBy}
                   />
@@ -557,33 +635,39 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
                 variant="outline"
                 size="sm"
                 id={items.length === 0 ? name : undefined}
-                onClick={() => setItems([...items, { ref: '', text: '' }])}
-                aria-invalid={items.length === 0 && errorMessage !== undefined ? true : undefined}
+                onClick={() => setItems([...items, { ref: "", text: "" }])}
+                aria-invalid={
+                  items.length === 0 && errorMessage !== undefined
+                    ? true
+                    : undefined
+                }
                 aria-describedby={items.length === 0 ? describedBy : undefined}
               >
                 Adicionar item
               </Button>
             </div>
-          )
+          );
         })()
-      ) : effectiveKind.kind === 'icon' ? (
+      ) : effectiveKind.kind === "icon" ? (
         // Widget 'icon': o value é o NOME do ícone (kebab-case) — ver <IconPicker>.
         <IconPicker
           id={name}
-          value={(formValues[name] as string | undefined) ?? ''}
+          value={(formValues[name] as string | undefined) ?? ""}
           onChange={(v) => setValue(v)}
-          placeholder={spec.placeholder ?? 'Selecione um ícone…'}
+          placeholder={spec.placeholder ?? "Selecione um ícone…"}
           aria-invalid={errorMessage !== undefined}
           aria-describedby={describedBy}
         />
-      ) : effectiveKind.kind === 'textarea' ? (
+      ) : effectiveKind.kind === "textarea" ? (
         // max-h: o Textarea v4 auto-cresce (field-sizing-content) — capa e scrolla
         // o CAMPO, não o form/dialog inteiro. widget 'code' = monoespaçado (SKILL.md).
         <Textarea
           id={name}
-          placeholder={spec.placeholder ?? ''}
+          placeholder={spec.placeholder ?? ""}
           rows={5}
-          className={spec.widget === 'code' ? 'max-h-80 font-mono text-xs' : 'max-h-80'}
+          className={
+            spec.widget === "code" ? "max-h-80 font-mono text-xs" : "max-h-80"
+          }
           aria-invalid={errorMessage !== undefined}
           aria-describedby={describedBy}
           {...form.register(name)}
@@ -591,7 +675,7 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
       ) : (
         <Input
           id={name}
-          placeholder={spec.placeholder ?? ''}
+          placeholder={spec.placeholder ?? ""}
           aria-invalid={errorMessage !== undefined}
           aria-describedby={describedBy}
           {...form.register(name)}
@@ -602,47 +686,53 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
         <FieldError id={errorId}>{errorMessage}</FieldError>
       )}
     </Field>
-  )
+  );
 }
 
 // =============================================================================
 // ActionForm
 // =============================================================================
 
-export interface ActionFormProps<TInput extends Record<string, unknown>, TData> {
-  action: FormContract<TInput, TData>
-  defaultValues?: Partial<TInput>
-  onSuccess?: (data: TData) => void
-  submitLabel?: string
-  cancelLabel?: string
-  onCancel?: () => void
+export interface ActionFormProps<
+  TInput extends Record<string, unknown>,
+  TData,
+> {
+  action: FormContract<TInput, TData>;
+  defaultValues?: Partial<TInput>;
+  onSuccess?: (data: TData) => void;
+  submitLabel?: string;
+  cancelLabel?: string;
+  /** Tratamento visual do cancelamento. Use outline quando ele dividir o footer com a ação principal. */
+  cancelVariant?: Extract<ButtonVariant, "ghost" | "outline">;
+  onCancel?: () => void;
   /** Bloqueia campos e ações sem desmontar o formulário. */
-  disabled?: boolean
+  disabled?: boolean;
   /** Informa carregamento para superfícies que coordenam ações como um grupo. */
-  onLoadingChange?: (loading: boolean) => void
+  onLoadingChange?: (loading: boolean) => void;
   /** Opções por campo pra select/multiselect carregados em runtime (ex.: papéis/skills
    *  por id). Sobrepõe as opções estáticas inferidas do z.enum. Chave = nome do campo. */
-  fieldOptions?: Record<string, SelectOption[]>
+  fieldOptions?: Record<string, SelectOption[]>;
   /** Classes do <form> (layout externo — ex.: coluna flex no dialog). */
-  className?: string
+  className?: string;
   /** Slot do CORPO: recebe os campos montados e decide o invólucro. Default: inline. No
    *  dialog, o ActionFormDialog injeta `DialogBody` (a área que rola). */
-  body?: (fields: React.ReactNode) => React.ReactNode
+  body?: (fields: React.ReactNode) => React.ReactNode;
   /** Slot do RODAPÉ: recebe os botões (Cancelar/Salvar) — com o estado do form e DENTRO
    *  do <form> — e decide o invólucro. Default: faixa de ação simples. No dialog, o
    *  ActionFormDialog injeta `DialogFooter` (a faixa da casa). */
-  footer?: (actions: React.ReactNode) => React.ReactNode
+  footer?: (actions: React.ReactNode) => React.ReactNode;
   /** Modo COMPOSIÇÃO: diagrame os campos com <ActionFormField name/> (grid, seções,
    *  condicionais em JSX). Sem children, o modo AUTO monta todos na ordem do contrato. */
-  children?: React.ReactNode
+  children?: React.ReactNode;
 }
 
 export function ActionForm<TInput extends Record<string, unknown>, TData>({
   action,
   defaultValues,
   onSuccess,
-  submitLabel = 'Salvar',
-  cancelLabel = 'Cancelar',
+  submitLabel = "Salvar",
+  cancelLabel = "Cancelar",
+  cancelVariant = "ghost",
   onCancel,
   disabled = false,
   onLoadingChange,
@@ -652,35 +742,53 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
   footer,
   children,
 }: ActionFormProps<TInput, TData>) {
-  const formId = useId()
-  const { form, submit, isLoading, error, isSuccess } = useFormAction<TInput, TData>(action, {
-    ...(defaultValues !== undefined ? { defaultValues: defaultValues as never } : {}),
+  const formId = useId();
+  const { form, submit, isLoading, error, isSuccess } = useFormAction<
+    TInput,
+    TData
+  >(action, {
+    ...(defaultValues !== undefined
+      ? { defaultValues: defaultValues as never }
+      : {}),
     onSuccess: (data) => {
-      toast.success(msgText(action.messages?.success, 'Concluído'))
-      onSuccess?.(data)
+      toast.success(msgText(action.messages?.success, "Concluído"));
+      onSuccess?.(data);
     },
     onError: (err) => {
-      toast.error(humanizeActionError(err, msgText(action.messages?.error, 'Não foi possível salvar.')))
+      toast.error(
+        humanizeActionError(
+          err,
+          msgText(action.messages?.error, "Não foi possível salvar."),
+        ),
+      );
     },
-  })
+  });
 
   useEffect(() => {
-    onLoadingChange?.(isLoading)
-    return () => onLoadingChange?.(false)
-  }, [isLoading, onLoadingChange])
+    onLoadingChange?.(isLoading);
+    return () => onLoadingChange?.(false);
+  }, [isLoading, onLoadingChange]);
 
-  const shape = (objectSchemaShape(action.input) ?? {}) as Record<string, ZodTypeAny | undefined>
-  const fields = action.fields as Record<string, FieldSpec>
+  const shape = (objectSchemaShape(action.input) ?? {}) as Record<
+    string,
+    ZodTypeAny | undefined
+  >;
+  const fields = action.fields as Record<string, FieldSpec>;
 
   // Corpo e rodapé como SLOTS: por padrão renderizam inline; o ActionFormDialog injeta
   // DialogBody/DialogFooter (fonte única do scroll e da faixa). Os botões ficam DENTRO do
   // <form> nos dois casos — o submit exige isso; o que muda é só o invólucro.
-  const wrapBody = body ?? ((fields: React.ReactNode) => fields)
+  const wrapBody = body ?? ((fields: React.ReactNode) => fields);
   const wrapFooter =
     footer ??
-    ((actions: React.ReactNode) => (
-      <div className="mt-6 flex shrink-0 justify-end gap-2">{actions}</div>
-    ))
+    ((actions: React.ReactNode) =>
+      onCancel === undefined ? (
+        <div className="mt-6 flex shrink-0 justify-end">{actions}</div>
+      ) : (
+        <ButtonGroup mode="spaced" className="mt-6 shrink-0 justify-end">
+          {actions}
+        </ButtonGroup>
+      ));
 
   // Banner de erro do servidor (chrome do próprio form, nos dois modos). O FieldGroup
   // mantém o mesmo ritmo entre campos, blocos compostos e este estado. Só a frase de
@@ -691,9 +799,12 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
         role="alert"
         className="rounded-md border border-context-danger-border bg-context-danger-subtle p-3 text-sm text-context-danger-emphasis"
       >
-        {humanizeActionError(error, msgText(action.messages?.error, 'Não foi possível salvar.'))}
+        {humanizeActionError(
+          error,
+          msgText(action.messages?.error, "Não foi possível salvar."),
+        )}
       </div>
-    ) : null
+    ) : null;
 
   return (
     <ActionFormContext.Provider
@@ -704,13 +815,20 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
         fieldOptions,
       }}
     >
-      <form id={formId} onSubmit={submit} className={cn('flex flex-col', className)} data-action={action.name}>
+      <form
+        id={formId}
+        onSubmit={submit}
+        className={cn("flex flex-col", className)}
+        data-action={action.name}
+      >
         {wrapBody(
           <fieldset disabled={disabled || isLoading} className="contents">
             <FieldGroup>
               {children !== undefined
                 ? children
-                : Object.keys(fields).map((name) => <ActionFormField key={name} name={name} />)}
+                : Object.keys(fields).map((name) => (
+                    <ActionFormField key={name} name={name} />
+                  ))}
               {errorBanner}
             </FieldGroup>
           </fieldset>,
@@ -722,7 +840,7 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
               <Button
                 type="button"
                 form={formId}
-                variant="ghost"
+                variant={cancelVariant}
                 disabled={disabled || isLoading}
                 onClick={onCancel}
               >
@@ -743,5 +861,5 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
         )}
       </form>
     </ActionFormContext.Provider>
-  )
+  );
 }