@softize/opus 13.1.0 → 15.0.0

package/src/ui/components/patterns/content-header.tsx

@@ -1,6 +1,5 @@
 import {
   Children,
-  Fragment,
   createContext,
   isValidElement,
   useContext,
@@ -10,9 +9,14 @@ import {
   type ReactNode,
 } from "react";
 import { cn } from "../../lib/cn.ts";
+import {
+  SurfaceHeader,
+  surfaceHeaderClasses,
+  type SurfaceHeaderVariant,
+} from "./surface-header.tsx";
 
 export type ContentHeaderLevel = 1 | 2 | 3 | 4 | 5 | 6;
-export type ContentHeaderVariant = "page" | "section";
+export type ContentHeaderVariant = SurfaceHeaderVariant;
 
 interface ContentContextValue {
   level: ContentHeaderLevel;
@@ -39,14 +43,14 @@ interface ContentBaseProps extends Omit<
 > {
   /** Nível semântico do heading, independente de seu destaque visual. */
   level?: ContentHeaderLevel;
-  /** Hierarquia visual. `page` permanece somente para compatibilidade durante a versão 12. */
+  /** Hierarquia visual: `section` (default) ou `page`, a mesma de PageHeader. */
   variant?: ContentHeaderVariant;
 }
 
 interface ContentShorthandProps extends ContentBaseProps {
   title: ReactNode;
-  /** Conteúdo complementar exibido ao lado do título, como uma contagem. */
-  meta?: ReactNode;
+  /** Total de itens ao lado do título — o mesmo `count` de Page. */
+  count?: number;
   description?: ReactNode;
   actions?: ReactNode;
   children: ReactNode;
@@ -54,7 +58,7 @@ interface ContentShorthandProps extends ContentBaseProps {
 
 interface ContentComposedProps extends ContentBaseProps {
   title?: never;
-  meta?: never;
+  count?: never;
   description?: never;
   actions?: never;
   children: ReactNode;
@@ -65,7 +69,7 @@ export type ContentProps = ContentShorthandProps | ContentComposedProps;
 /** Região de conteúdo nomeada. A forma curta e a explícita produzem a mesma anatomia. */
 export function Content({
   title,
-  meta,
+  count,
   description,
   actions,
   level = 2,
@@ -119,7 +123,7 @@ export function Content({
           <>
             <ContentHeader>
               <ContentTitle>{title}</ContentTitle>
-              {meta !== undefined && <ContentMeta>{meta}</ContentMeta>}
+              {count !== undefined && <ContentMeta>{count}</ContentMeta>}
               {description !== undefined && (
                 <ContentDescription>{description}</ContentDescription>
               )}
@@ -137,134 +141,36 @@ export function Content({
   );
 }
 
-interface ContentHeaderShorthandProps extends Omit<
-  HTMLAttributes<HTMLDivElement>,
-  "children" | "title"
-> {
-  /** @deprecated Prefira os slots explícitos ou o shorthand de Content. */
-  title: ReactNode;
-  meta?: ReactNode;
-  description?: ReactNode;
-  actions?: ReactNode;
-  /** @deprecated Declare o nível em Content. Compatibilidade da série 12. */
-  level?: ContentHeaderLevel;
-  /** @deprecated Declare a hierarquia visual em Content. Compatibilidade da série 12. */
-  variant?: ContentHeaderVariant;
-  children?: never;
-}
-
-interface ContentHeaderComposedProps extends Omit<
-  HTMLAttributes<HTMLDivElement>,
-  "title"
-> {
-  /** @deprecated Declare o nível em Content. Compatibilidade da série 12. */
-  level?: ContentHeaderLevel;
-  /** @deprecated Declare a hierarquia visual em Content. Compatibilidade da série 12. */
-  variant?: ContentHeaderVariant;
-  title?: never;
-  meta?: never;
-  description?: never;
-  actions?: never;
-  children: ReactNode;
-}
-
-export type ContentHeaderProps =
-  ContentHeaderShorthandProps | ContentHeaderComposedProps;
+export type ContentHeaderProps = Omit<HTMLAttributes<HTMLDivElement>, "title">;
 
 /**
- * Header estrutural de Content; não é uma região autônoma.
- *
- * Compartilha o layout (título, meta, descrição e ações) com `PageHeader` (page.tsx); os dois
- * serão unificados numa próxima série — até lá, uma correção de layout em um deve ser espelhada
- * no outro.
+ * Header estrutural de Content; não é uma região autônoma. A anatomia é a de
+ * `SurfaceHeader`, a mesma de `PageHeader`: só os nomes dos slots e a hierarquia mudam.
  */
 export function ContentHeader({
-  title,
-  meta,
-  description,
-  actions,
-  level,
-  variant,
   children,
-  className,
   ...props
 }: ContentHeaderProps): ReactElement {
-  const parent = useContext(ContentContext);
-  const standaloneTitleId = useId();
-  const shorthand = title !== undefined;
-  if (parent === null && !shorthand) {
-    throw new Error("ContentHeader deve estar dentro de Content.");
-  }
-  const content: ContentContextValue = {
-    level: level ?? parent?.level ?? 2,
-    titleId: parent?.titleId ?? standaloneTitleId,
-    variant: variant ?? parent?.variant ?? "section",
-  };
-  const nodes = Children.toArray(
-    shorthand ? (
-      <>
-        <ContentTitle>{title}</ContentTitle>
-        {meta !== undefined && <ContentMeta>{meta}</ContentMeta>}
-        {description !== undefined && (
-          <ContentDescription>{description}</ContentDescription>
-        )}
-        {actions !== undefined && <ContentActions>{actions}</ContentActions>}
-      </>
-    ) : (
-      children
-    ),
-  ).flatMap((node) =>
-    isValidElement(node) && node.type === Fragment
-      ? Children.toArray((node.props as { children?: ReactNode }).children)
-      : [node],
-  );
-  const titles = nodes.filter(
-    (node) => isValidElement(node) && node.type === ContentTitle,
-  );
-  const metas = nodes.filter(
-    (node) => isValidElement(node) && node.type === ContentMeta,
-  );
-  const descriptions = nodes.filter(
-    (node) => isValidElement(node) && node.type === ContentDescription,
-  );
-  const actionSlots = nodes.filter(
-    (node) => isValidElement(node) && node.type === ContentActions,
+  const content = requiredContext(
+    useContext(ContentContext),
+    "ContentHeader",
+    "Content",
   );
-  const recognized =
-    titles.length + metas.length + descriptions.length + actionSlots.length;
-
-  if (
-    titles.length !== 1 ||
-    metas.length > 1 ||
-    descriptions.length > 1 ||
-    actionSlots.length > 1 ||
-    recognized !== nodes.length
-  ) {
-    throw new Error(
-      "ContentHeader exige um ContentTitle e aceita no máximo um ContentDescription, ContentMeta e ContentActions como filhos diretos.",
-    );
-  }
-
   return (
     <ContentHeaderContext.Provider value={content}>
-      <div
-        data-slot="content-header"
-        className={cn(
-          actionSlots.length > 0 &&
-            "flex flex-col items-start gap-4 sm:flex-row sm:items-end sm:justify-between",
-          className,
-        )}
+      <SurfaceHeader
+        name="ContentHeader"
+        slot="content"
+        slots={{
+          title: ContentTitle,
+          count: ContentMeta,
+          description: ContentDescription,
+          actions: ContentActions,
+        }}
         {...props}
       >
-        <div data-slot="content-header-heading" className="min-w-0">
-          <div className="flex items-baseline gap-2">
-            {titles}
-            {metas}
-          </div>
-          {descriptions}
-        </div>
-        {actionSlots}
-      </div>
+        {children}
+      </SurfaceHeader>
     </ContentHeaderContext.Provider>
   );
 }
@@ -293,11 +199,7 @@ export function ContentTitle({
     <Heading
       id={id ?? context.titleId}
       data-slot="content-title"
-      className={cn(
-        "font-semibold",
-        context.variant === "page" ? "text-2xl tracking-tight" : "text-sm",
-        className,
-      )}
+      className={cn(surfaceHeaderClasses[context.variant].title, className)}
       {...props}
     />
   );
@@ -315,26 +217,29 @@ export function ContentDescription({
   return (
     <p
       data-slot="content-description"
-      className={cn(
-        "truncate text-muted-foreground",
-        context.variant === "page" ? "mt-1 text-sm" : "mt-0.5 text-xs",
-        className,
-      )}
+      className={cn(surfaceHeaderClasses[context.variant].description, className)}
       {...props}
     />
   );
 }
 
+/** O contador ao lado do título — o slot `count` do shorthand. */
 export function ContentMeta({
   className,
   ...props
 }: HTMLAttributes<HTMLSpanElement>): ReactElement {
-  requiredContext(
+  const context = requiredContext(
     useContext(ContentHeaderContext),
     "ContentMeta",
     "ContentHeader",
   );
-  return <span data-slot="content-meta" className={className} {...props} />;
+  return (
+    <span
+      data-slot="content-meta"
+      className={cn(surfaceHeaderClasses[context.variant].count, className)}
+      {...props}
+    />
+  );
 }
 
 export function ContentActions({
@@ -349,11 +254,7 @@ export function ContentActions({
   return (
     <div
       data-slot="content-actions"
-      className={cn(
-        "flex w-full shrink-0 items-center sm:w-auto",
-        context.variant === "page" ? "gap-4" : "gap-2",
-        className,
-      )}
+      className={cn(surfaceHeaderClasses[context.variant].actions, className)}
       {...props}
     />
   );

package/src/ui/components/patterns/data-state.tsx

@@ -2,31 +2,39 @@
  * <DataState /> — o estado "carregando" da casa: o que mostrar ANTES do conteúdo chegar.
  *
  * Orquestra os estados de uma carga assíncrona (lista/fetch) num lugar só: erro (calmo, sem
- * jargão na tela), carregando (Spinner centralizado), vazio (texto) e, por fim, o conteúdo.
+ * jargão na tela), carregando (Spinner centralizado), vazio (Empty) e, por fim, o conteúdo.
  * Dissolve o `error ? … : isLoading ? <Spinner/> : empty ? … : children` repetido em toda
  * tela. NÃO confundir com "processando" (AÇÃO em andamento depois do clique) — isso é o
  * `busy` do Button. Pra placeholder com forma de conteúdo, use Skeleton.
+ *
+ * As superfícies são as mesmas de PageState (state-surface.tsx); aqui elas ficam na escala de
+ * uma seção: o vazio é a frase discreta com moldura sólida e o erro é o Alert com recuperação.
  */
 import * as React from 'react'
-import { cn } from '../../lib/cn.ts'
-import { Alert } from '../primitives/alert.tsx'
-import { Button } from '../primitives/button.tsx'
-import { Spinner } from '../primitives/spinner.tsx'
+import {
+  DEFAULT_EMPTY_MESSAGE,
+  DEFAULT_ERROR_MESSAGE,
+  DEFAULT_RETRY_LABEL,
+  EmptySurface,
+  ErrorSurface,
+  LoadingSurface,
+} from './state-surface.tsx'
 
 export interface DataStateProps {
   /** Carregando (antes do conteúdo) — mostra o Spinner centralizado. */
   loading?: boolean
-  /** Erro da carga. A mensagem técnica NÃO vai pra tela (passe `errorText` pra um aviso). */
+  /** Erro da carga. A mensagem técnica NÃO vai pra tela (passe `errorMessage` pra um aviso). */
   error?: { message?: string } | null
-  /** Sem itens — mostra o `emptyText`. */
+  /** Sem itens — mostra o `emptyMessage`. */
   empty?: boolean
-  /** Texto do vazio (pt-BR, ex.: "Nenhum papel."). */
-  emptyText?: string
-  /** Aviso de erro (calmo, orientado ao usuário). Default: "Não foi possível carregar.". */
-  errorText?: string
+  /** Frase do vazio (pt-BR, ex.: "Nenhum papel."). Default: "Nada por aqui.". */
+  emptyMessage?: string
+  /** Aviso de erro (calmo, orientado à pessoa). Default: "Não foi possível carregar.". */
+  errorMessage?: string
   /** Recuperação opcional exibida somente no estado de erro. */
   onRetry?: () => Promise<void> | void
-  retryText?: string
+  /** Rótulo do botão de recuperação. Default: "Tentar de novo". */
+  retryLabel?: string
   /** Em TABELA: renderiza o estado como UMA linha (<tr><td colSpan>), não um bloco — pra
    *  caber direto no <tbody>. Passe o nº de colunas da tabela. */
   colSpan?: number
@@ -39,78 +47,44 @@ export function DataState({
   loading = false,
   error = null,
   empty = false,
-  emptyText = 'Nada por aqui.',
-  errorText,
+  emptyMessage = DEFAULT_EMPTY_MESSAGE,
+  errorMessage = DEFAULT_ERROR_MESSAGE,
   onRetry,
-  retryText = 'Tentar de novo',
+  retryLabel = DEFAULT_RETRY_LABEL,
   colSpan,
   children,
 }: DataStateProps): React.ReactElement {
   // Há conteúdo: passa direto (no modo tabela, são as <tr> dos itens).
   if (!error && !loading && !empty) return <>{children}</>
 
+  const status = error ? 'error' : loading ? 'loading' : 'empty'
+  const surface = error ? (
+    <ErrorSurface
+      title={errorMessage}
+      {...(onRetry !== undefined ? { onRetry } : {})}
+      retryLabel={retryLabel}
+    />
+  ) : loading ? (
+    <LoadingSurface className="py-10" />
+  ) : (
+    // A tabela já traz a moldura: dentro dela o vazio é só a frase (`bare`).
+    <EmptySurface title={emptyMessage} compact frame={colSpan === undefined ? 'structural' : 'bare'} />
+  )
+
   // Modo TABELA: o estado vira UMA linha de largura cheia (<td colSpan>), pra caber no <tbody>.
   if (colSpan !== undefined) {
-    const status = error ? 'error' : loading ? 'loading' : 'empty'
     return (
       <tr data-slot="data-state" data-status={status}>
-        <td
-          colSpan={colSpan}
-          className={cn('px-4 py-10 text-center text-sm', error ? 'text-context-danger-emphasis' : 'text-muted-foreground/60')}
-        >
-          {error ? (
-            <div className="flex flex-col items-center gap-3">
-              <span>{errorText ?? 'Não foi possível carregar.'}</span>
-              {onRetry !== undefined && (
-                <Button variant="outline" size="sm" onClick={() => void onRetry()}>
-                  {retryText}
-                </Button>
-              )}
-            </div>
-          ) : loading ? (
-            <Spinner className="mx-auto" />
-          ) : (
-            emptyText
-          )}
+        <td colSpan={colSpan} className="px-4 py-4 text-center text-sm">
+          {surface}
         </td>
       </tr>
     )
   }
 
-  // Modo BLOCO (default).
-  if (error) {
-    return (
-      <div data-slot="data-state" data-status="error">
-        <Alert context="danger" description={errorText ?? 'Não foi possível carregar.'}>
-          {onRetry !== undefined && (
-            <Button variant="outline" size="sm" onClick={() => void onRetry()}>
-              {retryText}
-            </Button>
-          )}
-        </Alert>
-      </div>
-    )
-  }
-  if (loading) {
-    return (
-      <div
-        data-slot="data-state"
-        data-status="loading"
-        role="status"
-        aria-live="polite"
-        className="py-10 text-center text-muted-foreground"
-      >
-        <Spinner className="mx-auto" />
-      </div>
-    )
-  }
   return (
-    <p
-      data-slot="data-state"
-      data-status="empty"
-      className="rounded-lg border border-border py-10 text-center text-sm text-muted-foreground/60"
-    >
-      {emptyText}
-    </p>
+    <div data-slot="data-state" data-status={status}>
+      {surface}
+    </div>
   )
 }

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

@@ -4,7 +4,7 @@
  * Dois modos, um motor:
  * - AUTO (sem children): monta TODOS os campos na ordem do contrato — zero JSX de campo.
  * - COMPOSIÇÃO (com children): você diagrama; <ActionFormField name /> coloca cada campo
- *   (label/hint/widget/erro/asterisco derivados do contrato) onde quiser. Condicional é
+ *   (label/help/widget/erro/asterisco derivados do contrato) onde quiser. Condicional é
  *   JSX ({cond && <ActionFormField/>}); opções de runtime entram por prop no campo. O
  *   FieldGroup canônico permanece nos dois modos; grids e seções entram como filhos explícitos.
  *
@@ -40,7 +40,7 @@ import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../pri
 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'
+import { Field, FieldError, FieldGroup, FieldLabel } from '../primitives/field.tsx'
 
 // =============================================================================
 // Inferência de tipo de field a partir do Zod schema
@@ -112,8 +112,6 @@ function inferFieldKind(schema: ZodTypeAny): FieldKind {
 interface FieldSpec {
   label?: string
   placeholder?: string
-  /** @deprecated Use `help` (ajuda junto à label) ou `description` do campo composto. */
-  hint?: string
   /** Ajuda na label: ícone ⓘ + tooltip no hover. */
   help?: string
   /** Override explícito do tipo de campo, quando o auto-detect do Zod não basta.
@@ -173,11 +171,18 @@ function dictMetaOptions(schema: ZodTypeAny): SelectOption[] | undefined {
   })
 }
 
-/** Ícone de ajuda na label (ⓘ + tooltip Radix). Self-contained (inclui o Provider) — só
- *  renderiza quando o FieldSpec define `help`. `tabIndex={-1}`: fica FORA do autofocus do
- *  diálogo (senão o modal foca no ícone ao abrir e 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). */
-function LabelHelp({ help }: { help: string | undefined }): React.ReactElement | null {
+/**
+ * Ícone de ajuda junto à label (ⓘ + tooltip Radix). Self-contained (inclui o Provider):
+ * renderiza somente quando `help` tem texto. É o mesmo slot que o `ActionFormField` usa para
+ * `FieldSpec.help`; exportado para que um formulário sem contrato mostre a ajuda no mesmo
+ * lugar (`<FieldLabel>Nome<LabelHelp help="…" /></FieldLabel>`) e o `opus copy` inventarie
+ * o texto de `help` como helper-text.
+ *
+ * `tabIndex={-1}`: fica FORA do autofocus do diálogo (senão o modal foca no ícone ao abrir e
+ * 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
   return (
     <TooltipProvider delayDuration={300}>
@@ -289,9 +294,8 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
   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
+  const describedBy = errorId
   useEffect(() => {
     if (errorMessage === undefined) return
     const control = document.getElementById(name)
@@ -373,7 +377,6 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
           </span>
           <LabelHelp help={spec.help} />
         </FieldLabel>
-        {spec.hint !== undefined && <FieldDescription id={descriptionId}>{spec.hint}</FieldDescription>}
         {errorMessage !== undefined && <FieldError id={errorId}>{errorMessage}</FieldError>}
       </Field>
     )
@@ -595,9 +598,6 @@ export function ActionFormField({ name, options: optionsProp, className }: Actio
         />
       )}
 
-      {spec.hint !== undefined && (
-        <FieldDescription id={descriptionId}>{spec.hint}</FieldDescription>
-      )}
       {errorMessage !== undefined && (
         <FieldError id={errorId}>{errorMessage}</FieldError>
       )}