@softize/opus 12.6.2 → 12.7.0

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

@@ -0,0 +1,113 @@
+import * as React from 'react'
+
+import { cn } from '../../lib/cn.ts'
+
+export type DetailGroupVariant = 'plain' | 'framed'
+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. */
+  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. */
+  columns?: DetailGroupColumns
+  /** Organiza a chave sobre o valor ou ao lado dele em cada campo. */
+  orientation?: DetailGroupOrientation
+}
+
+const columnClasses: Record<DetailGroupColumns, string> = {
+  1: 'grid-cols-1',
+  2: 'grid-cols-1 sm:grid-cols-2',
+  3: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3',
+  4: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-4',
+  auto: 'grid-cols-[repeat(auto-fit,minmax(min(100%,14rem),1fr))]',
+}
+
+function DetailGroup({
+  className,
+  variant = 'plain',
+  dividers = false,
+  columns = 1,
+  orientation = 'vertical',
+  ...props
+}: DetailGroupProps): React.ReactElement {
+  return (
+    <dl
+      data-slot="detail-group"
+      data-variant={variant}
+      data-dividers={dividers}
+      data-orientation={orientation}
+      className={cn(
+        'group/detail-group grid min-w-0',
+        columnClasses[columns],
+        variant === 'plain' && !dividers && 'gap-x-6 gap-y-4',
+        dividers && 'gap-px overflow-hidden',
+        (variant === 'framed' || dividers) &&
+          '[&>[data-slot=detail-field]]:p-3',
+        variant === 'framed' &&
+          'overflow-hidden rounded-lg border border-border bg-card text-card-foreground',
+        className,
+      )}
+      {...props}
+    />
+  )
+}
+
+export interface DetailFieldProps extends Omit<
+  React.ComponentProps<'div'>,
+  'children'
+> {
+  label: React.ReactNode
+  value: React.ReactNode
+  /** Ícone decorativo que identifica o campo antes do par chave/valor. */
+  icon?: React.ReactNode
+}
+
+function DetailField({
+  className,
+  label,
+  value,
+  icon,
+  ...props
+}: DetailFieldProps): React.ReactElement {
+  return (
+    <div
+      data-slot="detail-field"
+      className={cn(
+        'grid min-w-0 items-start',
+        'group-data-[orientation=vertical]/detail-group:grid-cols-1 group-data-[orientation=horizontal]/detail-group:grid-cols-[minmax(0,auto)_minmax(0,1fr)]',
+        'group-data-[orientation=vertical]/detail-group:gap-y-1 group-data-[orientation=horizontal]/detail-group:items-baseline group-data-[orientation=horizontal]/detail-group:gap-x-3',
+        'group-data-[dividers=true]/detail-group:outline group-data-[dividers=true]/detail-group:outline-1 group-data-[dividers=true]/detail-group:outline-border',
+        'group-data-[variant=framed]/detail-group:bg-card group-data-[variant=framed]/detail-group:text-card-foreground',
+        className,
+      )}
+      {...props}
+    >
+      <dt
+        data-slot="detail-field-label"
+        className="flex items-center gap-2.5 text-xs leading-snug font-medium text-muted-foreground group-data-[orientation=horizontal]/detail-group:text-sm"
+      >
+        {icon !== undefined && (
+          <span
+            data-slot="detail-field-icon"
+            aria-hidden="true"
+            className="flex size-4 shrink-0 items-center justify-center text-muted-foreground [&_svg]:size-4"
+          >
+            {icon}
+          </span>
+        )}
+        {label}
+      </dt>
+      <dd
+        data-slot="detail-field-value"
+        className="min-w-0 text-sm leading-snug font-normal"
+      >
+        {value}
+      </dd>
+    </div>
+  )
+}
+
+export { DetailGroup, DetailField }

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

@@ -93,6 +93,16 @@ ref }` resolve pelos dicts do `<TbdlibProvider dicts={{ ref: meuDict }}>` — o
 resolve value→label pela meta que viaja no contrato, sem registry) > **chaves cruas do
 z.enum**. Campo texto com opções declaradas (runtime ou spec) vira single-select por-id.
 
+## Widgets declarativos
+
+`FieldSpec.widget` aceita `textarea`, `code`, `lines`, `refItems`, `icon` e `toggle-group`.
+O literal canônico do grupo de escolhas é sempre kebab-case: `widget: 'toggle-group'`. Em enum ele
+renderiza seleção única; em array de enum, seleção múltipla. As opções seguem a mesma precedência e
+o mesmo `SelectOption` rico dos selects. Use esse widget quando cada opção funcionar como uma
+escolha rica em card, com conteúdo de apoio; para uma lista textual comum, prefira `RadioGroup`.
+Outros identificadores continuam válidos como metadado
+para renderers próprios; o `ActionForm` aplica sua inferência normal quando não reconhece o widget.
+
 ## Controle custom: useActionFormContext
 
 Campo com UI própria (grade de permissões, canvas…) que nenhum widget cobre? No modo

package/src/ui/docs/content/cli.md

@@ -16,8 +16,25 @@ valida as convenções e expõe o estado vivo pros agentes via MCP.
 opus check src    # valida as convenções das actions (exit ≠ 0 se violar)
 opus db check     # drift entidade ↔ banco (read-only)
 opus db migrate   # aplica o schema idempotente + drift-check na sequência
+opus seed check   # valida bindings, dependências, ciclos e comandos paralelos
 ```
 
+## Seeds de desenvolvimento e teste
+
+> Seeds registrados no `opus.config.ts` têm perfis, métricas e escopos explícitos. Listagem e gate
+> não abrem o banco; planejamento, aplicação e verificação são bloqueados em produção.
+
+```bash
+opus seed list
+opus seed plan customers.scenarios --profile smoke --scope local
+opus seed apply customers.scenarios --profile smoke --scope local
+opus seed verify customers.scenarios --profile smoke --scope local
+```
+
+`apply` converge quando repetido; não há reset ou truncate no contrato. A skill
+`$create-opus-seed` estrutura um novo dataset, e `$apply-opus-seed` opera um seed registrado pela
+mesma CLI.
+
 ## Geração e introspecção
 
 > As declarações (`description` de entidades/actions) são a fonte; o `gen` as projeta. O manifest

package/src/ui/docs/content/detail.md

@@ -0,0 +1,38 @@
+DetailGroup organiza dados somente leitura como uma lista semântica de pares chave/valor.
+DetailField representa cada par e aceita conteúdo React rico em `label` e `value`. Use Field
+para entrada e validação; use DetailField quando a pessoa apenas consulta um valor.
+
+```tsx preview col
+<DetailGroup columns={2}>
+  <DetailField label="Cliente" value="João Silva" />
+  <DetailField
+    label="Tipo"
+    value={<Badge variant="secondary">Prospect</Badge>}
+  />
+  <DetailField
+    className="sm:col-span-2"
+    label="E-mail"
+    value="joao.silva@example.com"
+    icon={<Mail />}
+  />
+</DetailGroup>
+```
+
+## Moldura e divisórias internas
+
+`variant="framed"` adiciona a superfície e a borda externa. `dividers` desenha apenas as
+divisórias internas; as duas opções são independentes e podem ser combinadas. `orientation`
+define se a chave fica sobre o valor ou ao lado dele.
+
+```tsx preview col
+<DetailGroup columns={2} orientation="horizontal" variant="framed" dividers>
+  <DetailField label="Documento" value="Sem documento" />
+  <DetailField label="Fontes" value="NBS e Followize" />
+  <DetailField
+    className="sm:col-span-2"
+    label="E-mail"
+    value="cliente@example.com"
+    icon={<Mail />}
+  />
+</DetailGroup>
+```

package/src/ui/docs/registry.tsx

@@ -67,6 +67,7 @@ import commandMd from './content/command.md?raw'
 import composerMd from './content/composer.md?raw'
 import copyableMd from './content/copyable.md?raw'
 import dialogMd from './content/dialog.md?raw'
+import detailMd from './content/detail.md?raw'
 import drawerMd from './content/drawer.md?raw'
 import menuMd from './content/menu.md?raw'
 import emptyMd from './content/empty.md?raw'
@@ -363,6 +364,7 @@ export const UI_SECTIONS: DocSection[] = [
           { slug: 'dock', title: 'Dock', render: comp('Dock', 'dock', dockMd) },
           { slug: 'carousel', title: 'Carousel', render: comp('Carousel', 'carousel', carouselMd) },
           { slug: 'copyable', title: 'Copyable', render: comp('Copyable', 'copyable', copyableMd) },
+          { slug: 'detail', title: 'Detail', render: comp('Detail', 'detail', detailMd) },
           { slug: 'item', title: 'Item', render: comp('Item', 'item', itemMd) },
           { slug: 'kbd', title: 'Kbd', render: comp('Kbd', 'kbd', kbdMd) },
           { slug: 'markdown', title: 'Markdown', render: comp('Markdown', 'markdown', markdownMd) },

package/src/ui/drivers/react.tsx

@@ -43,6 +43,7 @@ import {
   idleLookup,
 } from '../index.ts'
 import { zodErrorMapPtBr } from '../lib/zod-pt-br.ts'
+import { objectSchemaShape } from '../lib/object-schema.ts'
 
 // =============================================================================
 // Provider
@@ -327,8 +328,8 @@ export interface UseFormActionResult<TInput extends FieldValues, TData>
  * passa reto, fail-open).
  */
 function normalizeEmptyStrings(schema: unknown, values: Record<string, unknown>): Record<string, unknown> {
-  const shape = (schema as { shape?: Record<string, unknown> } | null)?.shape
-  if (shape === undefined || shape === null) return values
+  const shape = objectSchemaShape(schema)
+  if (shape === undefined) return values
   const out: Record<string, unknown> = { ...values }
   for (const [key, value] of Object.entries(out)) {
     if (value !== '') continue

package/src/ui/lib/object-schema.ts

@@ -0,0 +1,36 @@
+/**
+ * Encontra o shape de um objeto Zod atravessando wrappers como refine/superRefine.
+ * A inspeção é estrutural para funcionar com as representações v3 e v4 sem
+ * acoplar o driver React a uma única classe concreta do Zod.
+ */
+export function objectSchemaShape(schema: unknown): Record<string, unknown> | undefined {
+  let current = schema
+  const visited = new Set<object>()
+
+  while (current !== null && typeof current === 'object' && !visited.has(current)) {
+    visited.add(current)
+    const node = current as {
+      shape?: unknown
+      _def?: {
+        shape?: unknown
+        schema?: unknown
+        innerType?: unknown
+        in?: unknown
+      }
+    }
+    const directShape = node.shape
+    if (directShape !== null && typeof directShape === 'object' && !Array.isArray(directShape)) {
+      return directShape as Record<string, unknown>
+    }
+    const definedShape =
+      typeof node._def?.shape === 'function'
+        ? (node._def.shape as () => unknown)()
+        : node._def?.shape
+    if (definedShape !== null && typeof definedShape === 'object' && !Array.isArray(definedShape)) {
+      return definedShape as Record<string, unknown>
+    }
+    current = node._def?.schema ?? node._def?.innerType ?? node._def?.in
+  }
+
+  return undefined
+}

package/src/ui/meta.ts

@@ -35,6 +35,12 @@ export const componentMeta = {
     whenToUse:
       'Sinal compacto de estado quando o contexto ou o nome acessível já explica o significado. `variant` segue a intenção semântica (default/secondary/destructive/outline/success/warning/info). Passe `label` quando a cor comunicar informação; sem label, o ponto é decorativo. Para texto visível, use Badge.',
   },
+  'detail': {
+    name: 'detail',
+    ancestry: 'opus',
+    whenToUse:
+      'Dados somente leitura em pares chave/valor. Compõe DetailGroup > DetailField com semântica de lista de definições; `columns` controla a grade, `orientation` posiciona chave e valor, `variant="framed"` aplica moldura e `dividers` acrescenta somente as divisórias internas. Para entrada, validação e erro, use Field; para uma coleção pesquisável, use ActionList.',
+  },
   'dock': {
     name: 'dock',
     ancestry: 'opus',
@@ -341,7 +347,7 @@ export const componentMeta = {
     name: 'toggle-group',
     ancestry: 'shadcn',
     whenToUse:
-      'Grupo de botões de alternância (Radix). `type` single (um ativo, value: string) ou multiple (vários, value: string[]). Controlado por `value`/`onValueChange`. `variant` default|outline, `size` default|sm|lg e `spacing` descem pros itens via contexto. Pra alternar a visão de uma seção ou montar uma barra de formatação. Pra escolha única num form com rótulos longos, RadioGroup.',
+      'Grupo de botões de alternância (Radix). `type` single (um ativo, value: string) ou multiple (vários, value: string[]). Controlado por `value`/`onValueChange`. `variant` default|outline, `size` default|sm|lg e `spacing` descem pros itens via contexto. Serve para alternar a visão de uma seção, montar uma barra de formatação ou apresentar escolhas ricas em cards pelo `ActionForm` com `widget: toggle-group`. Para uma escolha textual comum em formulário, especialmente com rótulos longos sem conteúdo de apoio, prefira RadioGroup.',
   },
 
   'confirm': {

package/src/ui/react.tsx

@@ -47,6 +47,15 @@ export { Label } from './components/primitives/label.tsx'
 export { Badge, badgeVariants } from './components/primitives/badge.tsx'
 export type { BadgeProps } from './components/primitives/badge.tsx'
 
+export { DetailField, DetailGroup } from './components/primitives/detail.tsx'
+export type {
+  DetailFieldProps,
+  DetailGroupColumns,
+  DetailGroupOrientation,
+  DetailGroupProps,
+  DetailGroupVariant,
+} from './components/primitives/detail.tsx'
+
 export {
   Card,
   CardHeader,