@softize/opus 22.2.0 → 24.0.0

package/src/vite/design.ts

@@ -88,8 +88,8 @@ export interface OpusDesignOptions {
 
   /**
    * Cenários de design (ADR 0037): módulos que exportam `defineDesignScenario(contrato, resposta)`.
-   * Aceita caminhos e globs, como `entry`. O cenário vence o `mockHandler` e a resposta padrão
-   * gerada pelo `fake`; cenário de action inexistente impede o boot, com a lista no erro.
+   * Aceita caminhos e globs, como `entry`. O cenário vence a resposta padrão gerada pelo `fake`;
+   * cenário de action inexistente impede o boot, com a lista no erro.
    * Sem default: o projeto decide onde os cenários ficam e se são versionados.
    */
   scenarios?: string | string[]
@@ -116,7 +116,7 @@ export interface OpusDesignOptions {
   stubs?: Record<string, DesignStubHandler>
 
   /**
-   * Monta o /api também no dev NORMAL (handler real, sem OPUS_MODE).
+   * Monta o /api também no dev NORMAL, com os handlers reais.
    * Default false — devBackend puro não é design (sem sonda, proxy intacto).
    */
   devBackend?: boolean
@@ -156,7 +156,7 @@ const PROBE_PATH = '/__opus/design'
 const RUNTIME_ENDPOINT_PATHS = new Set(['/health', '/ready', '/openapi.json'])
 
 /** De onde vem a resposta de cada action no modo design, na ordem de precedência. */
-type DesignSource = 'scenario' | 'mock' | 'handler' | 'generated'
+type DesignSource = 'scenario' | 'handler' | 'generated'
 
 interface DesignState {
   handle: NodeServerHandle
@@ -214,9 +214,8 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
       exProxyPrefixes = Object.keys(config.server?.proxy ?? {})
       // 2) Mata o proxy: fecha o vazamento preview→prod pra QUALQUER prefixo.
       if (config.server?.proxy !== undefined) config.server.proxy = undefined
-      // 3) O execute() roteia pro mockHandler lendo OPUS_MODE (isOpusDesignMode); o boot
-      //    liga em cada action a resposta de design, e o preview fica autossuficiente.
-      process.env.OPUS_MODE = 'design'
+      // 3) O boot liga em cada contrato um handler de cenário ou resposta gerada,
+      //    e o preview fica autossuficiente sem alterar o runtime de produção.
     },
 
     configureServer(server) {
@@ -362,15 +361,14 @@ export function opusDesign(options: OpusDesignOptions = {}): Plugin {
           const named = (source: DesignSource): string[] =>
             state.actions.filter((a) => state.sources.get(a.name) === source).map((a) => a.name)
           const scenarios = named('scenario')
-          const mocks = named('mock')
           payload.runtime = {
             prefix: apiPrefix,
             actions: state.actions.length,
-            // `mocked`/`unmocked` mantêm o formato anterior da sonda: resposta escrita à mão
-            // (cenário ou mockHandler) contra o resto, que responde por handler real ou `fake`.
-            mocked: scenarios.length + mocks.length,
+            // `mocked`/`unmocked` preservam o formato histórico da sonda: cenário escrito
+            // à mão contra respostas vindas de handler real ou geradas pelo `fake`.
+            mocked: scenarios.length,
             unmocked: state.actions
-              .filter((a) => !['scenario', 'mock'].includes(state.sources.get(a.name) ?? ''))
+              .filter((a) => state.sources.get(a.name) !== 'scenario')
               .map((a) => a.name),
             scenarios,
             generated: named('generated'),
@@ -687,8 +685,8 @@ function scenariosOfModule(mod: Record<string, unknown>): DesignScenario[] {
 }
 
 /**
- * Liga a cada action a resposta de design, nesta precedência: cenário, `mockHandler` declarado,
- * handler real (`bindAction`) e, por fim, a resposta padrão gerada pelo `fake`.
+ * Liga a cada action a resposta de design, nesta precedência: cenário, handler real
+ * (`bindAction`) e, por fim, a resposta padrão gerada pelo `fake`.
  */
 function prepareDesignActions(
   actions: ActionDef[],
@@ -699,18 +697,23 @@ function prepareDesignActions(
     const scenario = scenarios.get(action.name)
     if (scenario !== undefined) {
       sources.set(action.name, 'scenario')
-      return { ...action, mockHandler: (ctx: ActionContext, input: unknown) => scenario.respond(input, ctx) } as ActionDef
-    }
-    if (action.mockHandler !== undefined) {
-      sources.set(action.name, 'mock')
-      return action
+      return {
+        ...action,
+        // Resposta simulada não representa exposição real de dado pessoal (ADR 0041).
+        personalData: false,
+        handler: (ctx: ActionContext, input: unknown) => scenario.respond(input, ctx),
+      } as ActionDef
     }
     if (typeof (action as { handler?: unknown }).handler === 'function') {
       sources.set(action.name, 'handler')
       return action
     }
     sources.set(action.name, 'generated')
-    return { ...action, mockHandler: async (_ctx: ActionContext, input: unknown) => designResponse(action, input) } as ActionDef
+    return {
+      ...action,
+      personalData: false,
+      handler: async (_ctx: ActionContext, input: unknown) => designResponse(action, input),
+    } as ActionDef
   })
   return { actions: prepared, sources }
 }
@@ -759,4 +762,3 @@ function sendEnvelope(res: ServerResponse, status: number, input: ErrorInput): v
     ),
   )
 }
-

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

@@ -1,532 +0,0 @@
-import {
-  Children,
-  createContext,
-  isValidElement,
-  useContext,
-  useId,
-  type ComponentProps,
-  type HTMLAttributes,
-  type ReactElement,
-  type ReactNode,
-} from "react";
-import { cn } from "../../lib/cn.ts";
-import { IconTile, type IconTileProps } from "../primitives/icon-tile.tsx";
-import { fillRegionClassName, useFillRegion } from "./fill-region.ts";
-import { headingTags } from "./heading-level.ts";
-import { usePageHeadingPresence } from "./page-heading-context.tsx";
-import type { SurfaceLayout } from "./surface-anatomy.ts";
-import { SurfaceMedia, type SurfaceMediaProps } from "./surface-media.tsx";
-import {
-  SurfaceHeader,
-  surfaceHeaderClasses,
-  type SurfaceHeaderVariant,
-} from "./surface-header.tsx";
-
-export type ContentHeaderLevel = 1 | 2 | 3 | 4 | 5 | 6;
-export type ContentHeaderVariant = SurfaceHeaderVariant;
-export type ContentElement = "section" | "fieldset";
-export type ContentFrameVariant = "default" | "legend";
-
-interface ContentContextValue {
-  element: ContentElement;
-  frameVariant: ContentFrameVariant;
-  framed: boolean;
-  layout: SurfaceLayout;
-  level: ContentHeaderLevel;
-  titleId: string;
-  variant: ContentHeaderVariant;
-}
-
-const ContentContext = createContext<ContentContextValue | null>(null);
-const ContentHeaderContext = createContext<ContentContextValue | null>(null);
-
-function requiredContext<T>(
-  value: T | null,
-  component: string,
-  parent: string,
-): T {
-  if (value === null)
-    throw new Error(`${component} deve estar dentro de ${parent}.`);
-  return value;
-}
-
-interface ContentSharedProps {
-  /** Aplica a moldura estrutural da região sem transferi-la ao conteúdo interno. */
-  framed?: boolean;
-  /** Anatomia interna: contínua (default) ou com header separado do corpo. */
-  layout?: SurfaceLayout;
-  /** Hierarquia visual: `section` (default) ou `page`, a mesma de PageHeader. */
-  variant?: ContentHeaderVariant;
-}
-
-interface ContentSectionBaseProps
-  extends
-    ContentSharedProps,
-    Omit<ComponentProps<"section">, "children" | "title"> {
-  /** Elemento semântico da região. */
-  as?: "section";
-  /** Tratamento visual da moldura: contínua (default) ou integrada ao header. */
-  frameVariant?: ContentFrameVariant;
-  /** Nível semântico do heading, independente de seu destaque visual. */
-  level?: ContentHeaderLevel;
-}
-
-interface ContentFieldsetBaseProps
-  extends
-    ContentSharedProps,
-    Omit<ComponentProps<"fieldset">, "children" | "title"> {
-  /** Usa a semântica nativa de grupo de campos; o título vira `legend`. */
-  as: "fieldset";
-  /** Tratamento visual da moldura: contínua (default) ou recortada pela legenda. */
-  frameVariant?: ContentFrameVariant;
-  level?: never;
-  variant?: "section";
-}
-
-interface ContentSectionShorthandProps extends ContentSectionBaseProps {
-  title: ReactNode;
-  /** Ícone ou imagem que identifica a região, antes do título. */
-  media?: ReactNode;
-  /** Total de itens ao lado do título da seção. A página não carrega contador (ADR 0009). */
-  count?: number;
-  description?: ReactNode;
-  actions?: ReactNode;
-  children: ReactNode;
-}
-
-interface ContentFieldsetShorthandProps extends ContentFieldsetBaseProps {
-  title: ReactNode;
-  /** Ícone ou imagem decorativa que acompanha o título dentro da legenda. */
-  media?: ReactNode;
-  count?: never;
-  description?: never;
-  actions?: never;
-  children: ReactNode;
-}
-
-interface ContentComposedProps {
-  title?: never;
-  media?: never;
-  count?: never;
-  description?: never;
-  actions?: never;
-  children: ReactNode;
-}
-
-export type ContentProps =
-  | ContentSectionShorthandProps
-  | ContentFieldsetShorthandProps
-  | ((ContentSectionBaseProps | ContentFieldsetBaseProps) &
-      ContentComposedProps);
-
-/** Região de conteúdo nomeada. A forma curta e a explícita produzem a mesma anatomia. */
-export function Content({
-  as = "section",
-  title,
-  media,
-  count,
-  description,
-  actions,
-  level = 2,
-  variant = "section",
-  framed = false,
-  layout = "continuous",
-  frameVariant = "default",
-  children,
-  className,
-  ...props
-}: ContentProps): ReactElement {
-  const titleId = useId();
-  const fill = useFillRegion();
-  const context = {
-    element: as,
-    frameVariant,
-    framed,
-    layout,
-    level: level as ContentHeaderLevel,
-    titleId,
-    variant,
-  };
-  const shorthand = title !== undefined;
-  const nodes = Children.toArray(children);
-
-  if (layout === "sectioned" && !framed) {
-    throw new Error('Content layout="sectioned" exige framed.');
-  }
-  if (layout === "sectioned" && frameVariant === "legend") {
-    throw new Error(
-      'Content não combina layout="sectioned" com frameVariant="legend".',
-    );
-  }
-
-  if (
-    shorthand &&
-    nodes.some((node) => isValidElement(node) && node.type === ContentHeader)
-  ) {
-    throw new Error(
-      "Content não permite misturar propriedades de shorthand com ContentHeader explícito.",
-    );
-  }
-  if (!shorthand) {
-    const headers = nodes.filter(
-      (node) => isValidElement(node) && node.type === ContentHeader,
-    );
-    const bodies = nodes.filter(
-      (node) => isValidElement(node) && node.type === ContentBody,
-    );
-    if (
-      headers.length !== 1 ||
-      bodies.length !== 1 ||
-      headers.length + bodies.length !== nodes.length
-    ) {
-      throw new Error(
-        "Content explícito exige exatamente um ContentHeader e um ContentBody como filhos diretos.",
-      );
-    }
-  }
-
-  const anatomy = shorthand ? (
-    <>
-      <ContentHeader>
-        {hasContentMedia(media) && <ContentMedia>{media}</ContentMedia>}
-        <ContentTitle>{title}</ContentTitle>
-        {count !== undefined && <ContentMeta>{count}</ContentMeta>}
-        {description !== undefined && (
-          <ContentDescription>{description}</ContentDescription>
-        )}
-        {actions !== undefined && <ContentActions>{actions}</ContentActions>}
-      </ContentHeader>
-      <ContentBody>{children}</ContentBody>
-    </>
-  ) : (
-    children
-  );
-  const ariaLabelledBy =
-    props["aria-label"] === undefined ? titleId : undefined;
-
-  return (
-    <ContentContext.Provider value={context}>
-      {as === "fieldset" ? (
-        <fieldset
-          data-slot="content"
-          data-as="fieldset"
-          data-framed={framed}
-          data-frame-variant={frameVariant}
-          data-layout={layout}
-          {...fill.attributes}
-          aria-labelledby={ariaLabelledBy}
-          className={cn(
-            !framed && layout === "continuous" && "space-y-3",
-            framed &&
-              layout === "continuous" &&
-              frameVariant === "default" &&
-              "rounded-xl border border-border p-4",
-            framed &&
-              layout === "continuous" &&
-              frameVariant === "legend" &&
-              "space-y-3 rounded-xl border border-border px-4 pb-4",
-            framed &&
-              layout === "sectioned" &&
-              "overflow-hidden rounded-xl border border-border",
-            fill.filling && fillRegionClassName,
-            className,
-          )}
-          {...(props as ComponentProps<"fieldset">)}
-        >
-          {fill.provide(anatomy)}
-        </fieldset>
-      ) : (
-        <section
-          data-slot="content"
-          data-as="section"
-          data-framed={framed}
-          data-frame-variant={frameVariant}
-          data-layout={layout}
-          {...fill.attributes}
-          aria-labelledby={ariaLabelledBy}
-          className={cn(
-            layout === "continuous" && "space-y-3",
-            framed &&
-              layout === "continuous" &&
-              frameVariant === "default" &&
-              "rounded-xl border border-border p-4",
-            framed &&
-              layout === "continuous" &&
-              frameVariant === "legend" &&
-              "rounded-xl border border-border px-4 pb-4",
-            framed &&
-              layout === "sectioned" &&
-              "overflow-hidden rounded-xl border border-border",
-            fill.filling && fillRegionClassName,
-            className,
-          )}
-          {...(props as ComponentProps<"section">)}
-        >
-          {fill.provide(anatomy)}
-        </section>
-      )}
-    </ContentContext.Provider>
-  );
-}
-
-export type ContentHeaderProps = Omit<HTMLAttributes<HTMLDivElement>, "title">;
-
-/**
- * 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({
-  className,
-  children,
-  ...props
-}: ContentHeaderProps): ReactElement {
-  const content = requiredContext(
-    useContext(ContentContext),
-    "ContentHeader",
-    "Content",
-  );
-  if (content.element === "fieldset") {
-    return (
-      <ContentHeaderContext.Provider value={content}>
-        <SurfaceHeader
-          as="legend"
-          name="ContentHeader"
-          slot="content"
-          slots={{ media: ContentMedia, title: ContentTitle }}
-          mediaPlacement="heading"
-          invalidMessage="ContentHeader de fieldset aceita somente ContentMedia e ContentTitle; contador, descrição e ações ficam fora da legenda."
-          className={cn(
-            content.framed &&
-              content.layout === "continuous" &&
-              content.frameVariant === "default" &&
-              "float-left w-full",
-            content.framed &&
-              content.layout === "continuous" &&
-              content.frameVariant === "legend" &&
-              "-ml-2 w-auto px-2",
-            content.framed &&
-              content.layout === "sectioned" &&
-              "float-left w-full border-b border-border p-3",
-            className,
-          )}
-          {...props}
-        >
-          {children}
-        </SurfaceHeader>
-      </ContentHeaderContext.Provider>
-    );
-  }
-  return (
-    <ContentHeaderContext.Provider value={content}>
-      <SurfaceHeader
-        name="ContentHeader"
-        slot="content"
-        slots={{
-          media: ContentMedia,
-          title: ContentTitle,
-          count: ContentMeta,
-          description: ContentDescription,
-          actions: ContentActions,
-        }}
-        mediaPlacement="heading"
-        className={cn(
-          content.framed &&
-            content.layout === "continuous" &&
-            content.frameVariant === "legend" &&
-            "flex items-center [&>[data-slot=content-actions]]:-mr-2 [&>[data-slot=content-actions]]:bg-[var(--surface-background,var(--background))] [&>[data-slot=content-actions]]:px-2 [&>[data-slot=content-heading]]:-ml-2 [&>[data-slot=content-heading]]:w-fit [&>[data-slot=content-heading]]:max-w-full [&>[data-slot=content-heading]]:bg-[var(--surface-background,var(--background))] [&>[data-slot=content-heading]]:px-2",
-          content.framed &&
-            content.layout === "continuous" &&
-            content.frameVariant === "legend" &&
-            content.variant === "section" &&
-            "-mt-4 min-h-8",
-          content.framed &&
-            content.layout === "continuous" &&
-            content.frameVariant === "legend" &&
-            content.variant === "page" &&
-            "-mt-5 min-h-10",
-          content.framed &&
-            content.layout === "sectioned" &&
-            "border-b border-border p-3",
-          content.variant === "page" &&
-            "flex-row items-center justify-start gap-3",
-          className,
-        )}
-        {...props}
-      >
-        {children}
-      </SurfaceHeader>
-    </ContentHeaderContext.Provider>
-  );
-}
-
-/** `null`, `false` e `undefined` não desenham mídia: uma moldura vazia não identifica nada. */
-function hasContentMedia(media: ReactNode): boolean {
-  return media !== undefined && media !== null && media !== false;
-}
-
-/**
- * Um `IconTile` recebido como filho não vira uma segunda moldura: o slot assume o lugar dele e
- * herda o que ele declara (`size`, `context`, `variant`, demais props), somando as classes.
- */
-function adoptIconTile(props: SurfaceMediaProps): SurfaceMediaProps {
-  const { children, asChild, className } = props;
-  if (asChild) return props;
-  // `toArray`, não `only`: um array com um único item (de um `map`/`filter`) é válido aqui.
-  const nodes = Children.toArray(children);
-  if (nodes.length !== 1) return props;
-  const child = nodes[0];
-  if (!isValidElement<IconTileProps>(child) || child.type !== IconTile) {
-    return props;
-  }
-  // `null` em size/context/variant significa "use o padrão" no IconTile: fica o do slot.
-  const declared = Object.fromEntries(
-    Object.entries(child.props).filter(([, value]) => value != null),
-  ) as SurfaceMediaProps;
-  return {
-    ...props,
-    ...declared,
-    className: cn(className, declared.className),
-    children: declared.children,
-  };
-}
-
-/** Moldura de ícone ou imagem que identifica a região nomeada. */
-export function ContentMedia({
-  size = "xs",
-  ...rest
-}: SurfaceMediaProps): ReactElement {
-  const context = requiredContext(
-    useContext(ContentHeaderContext),
-    "ContentMedia",
-    "ContentHeader",
-  );
-  const props = adoptIconTile({ size, ...rest });
-  return (
-    <SurfaceMedia
-      slot="content-media"
-      {...props}
-      aria-hidden={context.element === "fieldset" ? true : props["aria-hidden"]}
-    />
-  );
-}
-
-export function ContentTitle({
-  className,
-  id,
-  ...props
-}: HTMLAttributes<HTMLElement>): ReactElement {
-  const context = requiredContext(
-    useContext(ContentHeaderContext),
-    "ContentTitle",
-    "ContentHeader",
-  );
-  const Heading =
-    context.element === "fieldset" ? "span" : headingTags[context.level];
-  usePageHeadingPresence(context.element !== "fieldset" && context.level === 1);
-  return (
-    <Heading
-      id={id ?? context.titleId}
-      data-slot="content-title"
-      className={cn(surfaceHeaderClasses[context.variant].title, className)}
-      {...props}
-    />
-  );
-}
-
-export function ContentDescription({
-  className,
-  ...props
-}: HTMLAttributes<HTMLParagraphElement>): ReactElement {
-  const context = requiredContext(
-    useContext(ContentHeaderContext),
-    "ContentDescription",
-    "ContentHeader",
-  );
-  return (
-    <p
-      data-slot="content-description"
-      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 {
-  const context = requiredContext(
-    useContext(ContentHeaderContext),
-    "ContentMeta",
-    "ContentHeader",
-  );
-  return (
-    <span
-      data-slot="content-meta"
-      className={cn(surfaceHeaderClasses[context.variant].count, className)}
-      {...props}
-    />
-  );
-}
-
-export function ContentActions({
-  className,
-  ...props
-}: HTMLAttributes<HTMLDivElement>): ReactElement {
-  const context = requiredContext(
-    useContext(ContentHeaderContext),
-    "ContentActions",
-    "ContentHeader",
-  );
-  return (
-    <div
-      data-slot="content-actions"
-      className={cn(
-        surfaceHeaderClasses[context.variant].actions,
-        context.variant === "page" && "ml-auto w-auto",
-        className,
-      )}
-      {...props}
-    />
-  );
-}
-
-export function ContentBody({
-  className,
-  children,
-  ...props
-}: HTMLAttributes<HTMLDivElement>): ReactElement {
-  const content = requiredContext(
-    useContext(ContentContext),
-    "ContentBody",
-    "Content",
-  );
-  const fill = useFillRegion();
-  return (
-    <div
-      data-slot="content-body"
-      {...fill.attributes}
-      className={cn(
-        content.element === "fieldset" && "space-y-3",
-        content.element === "fieldset" &&
-          content.framed &&
-          content.layout === "continuous" &&
-          content.frameVariant === "default" &&
-          "clear-left pt-3",
-        content.element === "fieldset" &&
-          content.framed &&
-          content.layout === "sectioned" &&
-          "clear-left",
-        fill.filling && fillRegionClassName,
-        className,
-      )}
-      {...props}
-    >
-      {fill.provide(children)}
-    </div>
-  );
-}