@softize/opus 12.6.2 → 12.7.0

package/registry/skills/implement-opus-change/SKILL.md

@@ -5,6 +5,7 @@ description: Implementa uma mudança em projeto baseado no Opus preservando cont
 <!-- softize-skill-route: $create-opus-action -->
 <!-- softize-skill-route: $test-opus-action -->
 <!-- softize-skill-route: $build-opus-ui -->
+<!-- softize-skill-route: $create-opus-seed -->
 
 # Implementar mudança Opus
 
@@ -25,7 +26,8 @@ dependências server-only, bindings registrados, testes e gates verdes.
 2. Modelar primeiro o contrato observável: nome, descrição, input, output, erros e metadata.
 3. Manter código compartilhável fora de banco, segredo, filesystem e drivers server-only.
 4. Implementar o binding e registrar o `ActionDef` no domínio/runtime conforme a topologia local.
-5. Carregar e seguir `$create-opus-action`, `$test-opus-action` ou `$build-opus-ui` antes
+5. Carregar e seguir `$create-opus-action`, `$test-opus-action`, `$build-opus-ui` ou
+   `$create-opus-seed` antes
    do passo correspondente quando a mudança entrar nesses workflows especializados.
 6. Atualizar manifest, docs geradas e exemplos somente pelos comandos do repo.
 

package/src/core/index.ts

@@ -54,6 +54,8 @@ export type {
   Example,
   ActionMessages,
   OptionsSpec,
+  BuiltInFieldWidget,
+  FieldWidget,
   FieldSpec,
   FilterOp,
   FilterSpec,

package/src/core/types.ts

@@ -529,6 +529,21 @@ export type OptionsSpec =
   | { kind: 'dictionary'; ref: string }
   | { kind: 'lookup'; source: string; depends?: string[] }
 
+/** Overrides declarativos nativos reconhecidos pelo ActionForm. */
+export type BuiltInFieldWidget =
+  | 'textarea'
+  | 'code'
+  | 'lines'
+  | 'refItems'
+  | 'icon'
+  | 'toggle-group'
+
+/**
+ * Widget nativo ou identificador próprio de outro renderer.
+ * A interseção preserva autocomplete dos nativos sem quebrar widgets customizados existentes.
+ */
+export type FieldWidget = BuiltInFieldWidget | (string & { readonly __opusCustomWidget?: never })
+
 /**
  * Descrição de campo em `FormAction.fields`. Drive UI rendering + AI tool
  * description per-field.
@@ -551,7 +566,7 @@ export interface FieldSpec {
   group?: string
   order?: number
 
-  widget?: string
+  widget?: FieldWidget
   options?: OptionsSpec
 
   aiDescription?: string

package/src/seed/index.ts

@@ -0,0 +1,391 @@
+/**
+ * Seeds estruturados são operações de projeto, não actions do runtime.
+ *
+ * `defineSeed` mantém a declaração pura e compartilhável. `bindSeed` liga a
+ * implementação server-only que a CLI carrega pelo `opus.config.ts`.
+ */
+
+export interface SeedProfile {
+  /** Situação que este perfil representa para quem vai aplicá-lo. */
+  description: string
+  /** Métricas que `verify` precisa encontrar após uma aplicação bem-sucedida. */
+  expected?: Readonly<Record<string, number>>
+}
+
+export interface SeedSafety {
+  /** Escopos de dados em que o seed pode abrir conexão. */
+  scopes: readonly SeedScope[]
+}
+
+export type SeedScope = 'local' | 'test' | 'isolated-preview'
+
+export interface SeedDefinition {
+  /** Identidade estável, em segmentos lowercase separados por ponto. */
+  name: string
+  /** Versão positiva do dataset e de suas invariantes. */
+  version: number
+  description: string
+  profiles: Readonly<Record<string, SeedProfile>>
+  defaultProfile: string
+  dependsOn?: readonly string[]
+  safety: SeedSafety
+}
+
+export interface SeedContext<Database = unknown> {
+  database: Database | null
+  profile: string
+  scope: SeedScope
+}
+
+export interface SeedTargetContext<Database = unknown> {
+  database: Database | null
+  scope: SeedScope
+}
+
+/**
+ * Atesta que a conexão aberta corresponde ao escopo solicitado, antes de qualquer binding.
+ * Deve retornar `true` explicitamente; ausência de retorno e valores falsos falham fechado.
+ */
+export type SeedTargetAssertion<Database = unknown> = (
+  context: SeedTargetContext<Database>,
+) => boolean | Promise<boolean>
+
+export interface SeedPlan {
+  summary: string
+  operations: readonly string[]
+}
+
+export interface SeedReport {
+  summary: string
+  metrics: Readonly<Record<string, number>>
+}
+
+export interface SeedBinding<Database = unknown> {
+  plan(context: SeedContext<Database>): SeedPlan | Promise<SeedPlan>
+  apply(context: SeedContext<Database>): SeedReport | Promise<SeedReport>
+  verify(context: SeedContext<Database>): SeedReport | Promise<SeedReport>
+}
+
+export interface BoundSeed<Database = unknown> extends SeedDefinition {
+  readonly binding: SeedBinding<Database>
+}
+
+export type SeedRegistryItem = SeedDefinition | BoundSeed
+
+export interface SeedDiagnostic {
+  code:
+    | 'seed.duplicate'
+    | 'seed.unbound'
+    | 'seed.missing_dependency'
+    | 'seed.cyclic_dependency'
+  message: string
+  seed: string
+}
+
+export interface SeedRegistryCheck {
+  ok: boolean
+  diagnostics: readonly SeedDiagnostic[]
+  /** Ordem topológica; dependências aparecem antes de seus consumidores. */
+  ordered: readonly BoundSeed[]
+}
+
+const SEED_NAME_RE = /^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)+$/
+const PROFILE_RE = /^[a-z][a-z0-9-]*$/
+const SCOPE_RE = /^[a-z][a-z0-9-]*$/
+const SEED_SCOPES = new Set<SeedScope>(['local', 'test', 'isolated-preview'])
+
+export function defineSeed<const Definition extends SeedDefinition>(
+  definition: Definition,
+): Definition {
+  validateDefinition(definition)
+  return definition
+}
+
+/**
+ * Projeta somente os metadados públicos do seed.
+ *
+ * A projeção é deliberadamente profunda: objetos recebidos de TypeScript ou
+ * JavaScript podem carregar campos adicionais, mas manifestos e respostas da
+ * CLI nunca devem reproduzi-los por espalhamento ou referência.
+ */
+export function publicSeedDefinition(seed: SeedDefinition): SeedDefinition {
+  validateDefinition(seed)
+  return {
+    name: seed.name,
+    version: seed.version,
+    description: seed.description,
+    profiles: Object.fromEntries(
+      Object.entries(seed.profiles).map(([name, profile]) => [
+        name,
+        {
+          description: profile.description,
+          ...(profile.expected === undefined ? {} : { expected: { ...profile.expected } }),
+        },
+      ]),
+    ),
+    defaultProfile: seed.defaultProfile,
+    ...(seed.dependsOn === undefined ? {} : { dependsOn: [...seed.dependsOn] }),
+    safety: { scopes: [...seed.safety.scopes] },
+  }
+}
+
+export function bindSeed<Database = unknown>(
+  definition: SeedDefinition,
+  binding: SeedBinding<Database>,
+): BoundSeed<Database> {
+  validateDefinition(definition)
+  validateBinding(binding)
+  return { ...definition, binding }
+}
+
+export function isSeedDefinition(value: unknown): value is SeedDefinition {
+  try {
+    validateDefinition(value)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function isBoundSeed(value: unknown): value is BoundSeed {
+  if (!isSeedDefinition(value)) return false
+  try {
+    validateBinding((value as Partial<BoundSeed>).binding)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function checkSeedRegistry(items: readonly SeedRegistryItem[]): SeedRegistryCheck {
+  const diagnostics: SeedDiagnostic[] = []
+  const byName = new Map<string, BoundSeed>()
+  const seen = new Set<string>()
+
+  for (const item of items) {
+    validateDefinition(item)
+    if (seen.has(item.name)) {
+      diagnostics.push({
+        code: 'seed.duplicate',
+        seed: item.name,
+        message: `Seed duplicado: ${item.name}`,
+      })
+      continue
+    }
+    seen.add(item.name)
+    if (!isBoundSeed(item)) {
+      diagnostics.push({
+        code: 'seed.unbound',
+        seed: item.name,
+        message: `Seed ${item.name} precisa de plan, apply e verify via bindSeed`,
+      })
+      continue
+    }
+    byName.set(item.name, item)
+  }
+
+  for (const item of items) {
+    for (const dependency of item.dependsOn ?? []) {
+      if (!seen.has(dependency)) {
+        diagnostics.push({
+          code: 'seed.missing_dependency',
+          seed: item.name,
+          message: `Seed ${item.name} depende de ${dependency}, que não está registrado`,
+        })
+      }
+    }
+  }
+
+  const ordered: BoundSeed[] = []
+  const visiting = new Set<string>()
+  const visited = new Set<string>()
+  const cycles = new Set<string>()
+
+  const visit = (name: string, path: readonly string[]): void => {
+    if (visited.has(name)) return
+    if (visiting.has(name)) {
+      const start = path.indexOf(name)
+      const cycle = [...path.slice(start), name]
+      const key = cycle.join(' -> ')
+      if (!cycles.has(key)) {
+        cycles.add(key)
+        diagnostics.push({
+          code: 'seed.cyclic_dependency',
+          seed: name,
+          message: `Dependência cíclica entre seeds: ${key}`,
+        })
+      }
+      return
+    }
+    const seed = byName.get(name)
+    if (seed === undefined) return
+    visiting.add(name)
+    for (const dependency of seed.dependsOn ?? []) visit(dependency, [...path, name])
+    visiting.delete(name)
+    visited.add(name)
+    ordered.push(seed)
+  }
+
+  for (const name of byName.keys()) visit(name, [])
+
+  return {
+    ok: diagnostics.length === 0,
+    diagnostics,
+    ordered: diagnostics.some((diagnostic) => diagnostic.code === 'seed.cyclic_dependency')
+      ? []
+      : ordered,
+  }
+}
+
+export function resolveSeedProfile(seed: SeedDefinition, requested?: string): string {
+  const profile = requested ?? seed.defaultProfile
+  if (!Object.hasOwn(seed.profiles, profile)) {
+    throw new Error(
+      `Perfil ${profile} não existe no seed ${seed.name}; disponíveis: ${Object.keys(seed.profiles).join(', ')}`,
+    )
+  }
+  return profile
+}
+
+export function assertSeedExecutionAllowed(
+  seed: SeedDefinition,
+  scope: string | undefined,
+  environment = runtimeNodeEnvironment(),
+): asserts scope is SeedScope {
+  const normalizedEnvironment = environment?.trim().toLowerCase()
+  if (normalizedEnvironment !== 'development' && normalizedEnvironment !== 'test') {
+    throw new Error('Seeds exigem NODE_ENV=development ou NODE_ENV=test antes de abrir conexão')
+  }
+  if (scope === undefined || scope.trim().length === 0) {
+    throw new Error('Informe --scope ou OPUS_SEED_SCOPE antes de abrir o banco')
+  }
+  if (!seed.safety.scopes.some((allowedScope) => allowedScope === scope)) {
+    throw new Error(
+      `Escopo ${scope} não é permitido para ${seed.name}; permitidos: ${seed.safety.scopes.join(', ')}`,
+    )
+  }
+}
+
+function runtimeNodeEnvironment(): string | undefined {
+  return (
+    globalThis as typeof globalThis & {
+      process?: { env?: { NODE_ENV?: string } }
+    }
+  ).process?.env?.NODE_ENV
+}
+
+export function validateSeedPlan(value: unknown): SeedPlan {
+  if (!isRecord(value) || !isNonEmptyString(value.summary) || !Array.isArray(value.operations)) {
+    throw new Error('plan precisa retornar { summary, operations }')
+  }
+  if (!value.operations.every(isNonEmptyString)) {
+    throw new Error('plan.operations precisa conter somente descrições não vazias')
+  }
+  return value as unknown as SeedPlan
+}
+
+export function validateSeedReport(value: unknown): SeedReport {
+  if (!isRecord(value) || !isNonEmptyString(value.summary) || !isMetrics(value.metrics)) {
+    throw new Error('apply/verify precisa retornar { summary, metrics } com valores numéricos finitos')
+  }
+  return value as unknown as SeedReport
+}
+
+export function assertSeedExpectedMetrics(
+  seed: SeedDefinition,
+  profile: string,
+  report: SeedReport,
+): void {
+  const expected = seed.profiles[profile]?.expected
+  if (expected === undefined) return
+  const mismatches = Object.entries(expected).flatMap(([metric, wanted]) => {
+    const actual = report.metrics[metric]
+    return actual === wanted ? [] : [`${metric}: esperado ${wanted}, encontrado ${String(actual)}`]
+  })
+  if (mismatches.length > 0) {
+    throw new Error(`Verificação de ${seed.name} falhou — ${mismatches.join('; ')}`)
+  }
+}
+
+function validateDefinition(value: unknown): asserts value is SeedDefinition {
+  if (!isRecord(value)) throw new Error('Seed precisa ser um objeto')
+  if (typeof value.name !== 'string' || !SEED_NAME_RE.test(value.name)) {
+    throw new Error('Seed name deve usar ao menos dois segmentos lowercase, como customers.scenarios')
+  }
+  if (!Number.isInteger(value.version) || Number(value.version) <= 0) {
+    throw new Error(`Seed ${value.name} precisa de version inteira positiva`)
+  }
+  if (!isNonEmptyString(value.description)) {
+    throw new Error(`Seed ${value.name} precisa de description`)
+  }
+  if (!isRecord(value.profiles) || Object.keys(value.profiles).length === 0) {
+    throw new Error(`Seed ${value.name} precisa de ao menos um profile`)
+  }
+  for (const [profileName, profile] of Object.entries(value.profiles)) {
+    if (!PROFILE_RE.test(profileName)) {
+      throw new Error(`Profile ${profileName} de ${value.name} possui nome inválido`)
+    }
+    if (!isRecord(profile) || !isNonEmptyString(profile.description)) {
+      throw new Error(`Profile ${profileName} de ${value.name} precisa de description`)
+    }
+    if (profile.expected !== undefined && !isMetrics(profile.expected)) {
+      throw new Error(`Profile ${profileName} de ${value.name} possui métricas esperadas inválidas`)
+    }
+  }
+  if (typeof value.defaultProfile !== 'string' || !Object.hasOwn(value.profiles, value.defaultProfile)) {
+    throw new Error(`defaultProfile de ${value.name} precisa apontar para um profile existente`)
+  }
+  if (value.dependsOn !== undefined) {
+    if (!Array.isArray(value.dependsOn)) throw new Error(`dependsOn de ${value.name} precisa ser uma lista`)
+    const dependencies = value.dependsOn
+    const unique = new Set(dependencies)
+    if (
+      dependencies.some((dependency) => typeof dependency !== 'string' || !SEED_NAME_RE.test(dependency)) ||
+      unique.size !== dependencies.length ||
+      unique.has(value.name)
+    ) {
+      throw new Error(`dependsOn de ${value.name} possui dependência inválida, repetida ou autorreferente`)
+    }
+  }
+  if (!isRecord(value.safety) || !Array.isArray(value.safety.scopes) || value.safety.scopes.length === 0) {
+    throw new Error(`Seed ${value.name} precisa declarar safety.scopes`)
+  }
+  const scopes = value.safety.scopes
+  if (
+    scopes.some((scope) => typeof scope !== 'string' || !SCOPE_RE.test(scope)) ||
+    new Set(scopes).size !== scopes.length ||
+    scopes.some((scope) => !SEED_SCOPES.has(scope as SeedScope))
+  ) {
+    throw new Error(
+      `safety.scopes de ${value.name} aceita somente local, test e isolated-preview, sem repetições`,
+    )
+  }
+}
+
+function validateBinding(value: unknown): asserts value is SeedBinding {
+  if (
+    !isRecord(value) ||
+    typeof value.plan !== 'function' ||
+    typeof value.apply !== 'function' ||
+    typeof value.verify !== 'function'
+  ) {
+    throw new Error('bindSeed exige as funções plan, apply e verify')
+  }
+}
+
+function isMetrics(value: unknown): value is Readonly<Record<string, number>> {
+  return (
+    isRecord(value) &&
+    Object.entries(value).every(
+      ([name, metric]) => isNonEmptyString(name) && typeof metric === 'number' && Number.isFinite(metric),
+    )
+  )
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0
+}

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

@@ -17,12 +17,18 @@
  * inline; toast em sucesso/erro. Emite `data-action="<action.name>"` na raiz (selector E2E).
  */
 
-import { createContext, useContext } from 'react'
+import { createContext, useContext, useEffect } from 'react'
 import type { UseFormReturn } from 'react-hook-form'
-import { getLogicalType, type FormContract, type OptionsSpec } from '../../../core/index.ts'
+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 { objectSchemaShape } from '../../lib/object-schema.ts'
 import { toast } from '../primitives/sonner.tsx'
 import { Button } from '../primitives/button.tsx'
 import { Input } from '../primitives/input.tsx'
@@ -32,6 +38,7 @@ 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, FieldDescription, FieldError, FieldGroup, FieldLabel } from '../primitives/field.tsx'
 
 // =============================================================================
@@ -44,6 +51,7 @@ type FieldKind =
   | { 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 }
@@ -111,8 +119,9 @@ interface FieldSpec {
    *  'lines' (z.array(z.string()) num textarea, um item por linha), 'refItems'
    *  (z.array(z.object({ref, text})) — linhas de referência + texto; as opções do
    *  `ref` vêm de fieldOptions[campo]) e 'icon' (string com o nome kebab-case da
-   *  paleta da casa — renderiza o <IconPicker>). */
-  widget?: string
+   *  paleta da casa — renderiza o <IconPicker>) e 'toggle-group' para escolhas
+   *  declarativas com opções ricas. */
+  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
@@ -194,14 +203,16 @@ function LabelHelp({ help }: { help: string | undefined }): React.ReactElement |
   )
 }
 
-/** Asterisco de obrigatório na label — derivado do Zod (campo sem optional/default).
- *  aria-hidden: leitor de tela valida pelo erro do resolver, não pelo símbolo. */
+/** 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
   return (
-    <span aria-hidden className="ml-0.5 text-destructive">
-      *
-    </span>
+    <>
+      <span aria-hidden className="ml-0.5 text-destructive">
+        *
+      </span>
+      <span className="sr-only"> (obrigatório)</span>
+    </>
   )
 }
 
@@ -264,7 +275,30 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
   // Assina TODOS os valores: alimenta o showWhen e os widgets controlados.
   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
+    }
+    control?.focus()
+  }
+
   const spec: FieldSpec = fields[name] ?? {}
+  const fieldError = form.formState.errors[name]
+  const errorMessage = typeof fieldError?.message === 'string' ? fieldError.message : undefined
+  const descriptionId = spec.hint !== undefined ? `${name}-description` : undefined
+  const errorId = errorMessage !== undefined ? `${name}-error` : undefined
+  const describedBy = [descriptionId, errorId].filter(Boolean).join(' ') || undefined
+  useEffect(() => {
+    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
@@ -280,12 +314,17 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
           ? { kind: 'refItems', required: inferred.required }
           : spec.widget === 'icon'
             ? { kind: 'icon', required: inferred.required }
-            : inferred
-  const fieldError = form.formState.errors[name]
-  const errorMessage = typeof fieldError?.message === 'string' ? fieldError.message : undefined
-  const descriptionId = spec.hint !== undefined ? `${name}-description` : undefined
-  const errorId = errorMessage !== undefined ? `${name}-error` : undefined
-  const describedBy = [descriptionId, errorId].filter(Boolean).join(' ') || undefined
+            : spec.widget === 'toggle-group'
+              ? {
+                  kind: 'toggle-group',
+                  required: inferred.required,
+                  multiple: inferred.kind === 'multiselect',
+                  options:
+                    inferred.kind === 'select' || inferred.kind === 'multiselect'
+                      ? inferred.options
+                      : [],
+                }
+              : 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.
@@ -295,7 +334,9 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
   const options: SelectOption[] =
     declaredOptions ??
     dictMetaOptions(fieldSchema) ??
-    (fieldKind.kind === 'select' || fieldKind.kind === 'multiselect'
+    (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.
@@ -343,7 +384,7 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
       aria-invalid={errorMessage !== undefined}
       aria-describedby={describedBy}
     >
-      <FieldLabel htmlFor={name} 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} />
@@ -351,7 +392,78 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
         <LabelHelp help={spec.help} />
       </FieldLabel>
 
-      {effectiveKind.kind === 'multiselect' ? (
+      {effectiveKind.kind === 'toggle-group' ? (
+        effectiveKind.multiple ? (
+          <ToggleGroup
+            type="multiple"
+            id={name}
+            value={(formValues[name] as string[] | undefined) ?? []}
+            onValueChange={(value) => setValue(value)}
+            variant="outline"
+            spacing={2}
+            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
+                key={option.value}
+                value={option.value}
+                disabled={option.disabled}
+                aria-label={option.label}
+                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>
+                  {option.hint !== undefined && (
+                    <span className="mt-1 block text-xs font-normal text-muted-foreground">
+                      {option.hint}
+                    </span>
+                  )}
+                </span>
+              </ToggleGroupItem>
+            ))}
+          </ToggleGroup>
+        ) : (
+          <ToggleGroup
+            type="single"
+            id={name}
+            value={(formValues[name] as string | undefined) ?? ''}
+            onValueChange={(value) => {
+              if (value !== '' || !effectiveKind.required) {
+                setValue(value === '' ? undefined : value)
+              }
+            }}
+            variant="outline"
+            spacing={2}
+            aria-labelledby={`${name}-label`}
+            aria-required={effectiveKind.required}
+            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
+                key={option.value}
+                value={option.value}
+                disabled={option.disabled}
+                aria-label={option.label}
+                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>
+                  {option.hint !== undefined && (
+                    <span className="mt-1 block text-xs font-normal text-muted-foreground">
+                      {option.hint}
+                    </span>
+                  )}
+                </span>
+              </ToggleGroupItem>
+            ))}
+          </ToggleGroup>
+        )
+      ) : effectiveKind.kind === 'multiselect' ? (
         <Select
           multiple
           searchable
@@ -543,7 +655,7 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
     },
   })
 
-  const shape = (action.input as unknown as z.ZodObject<z.ZodRawShape>).shape
+  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