@softize/opus 18.5.0 → 20.0.0

package/src/core/runtime.ts

@@ -413,9 +413,35 @@ export class Runtime {
         })
       }
       this.actions.set(action.name, action)
+      if (this.config.dev) this.warnIgnoredExecutionFields(action)
     }
   }
 
+  /**
+   * `emits` e `background` pertencem ao binding de qualquer kind pelo tipo, mas o runtime e o
+   * manifest só os aplicam em `simple` e `form`. Restringir o tipo quebraria bindings
+   * existentes; o aviso em desenvolvimento evita que a declaração pareça ter efeito.
+   */
+  private warnIgnoredExecutionFields(action: ActionDef): void {
+    if (action.kind !== 'list' && action.kind !== 'view') return
+    const declared = action as { emits?: unknown; background?: unknown }
+    const fields = (['emits', 'background'] as const).filter((field) => declared[field] !== undefined)
+    if (fields.length === 0) return
+    const list = fields.map((field) => `\`${field}\``).join(' e ')
+    const effects = fields.map((field) =>
+      field === 'background'
+        ? 'Sem fila, a action executa na própria requisição.'
+        : 'Os eventos declarados não entram no manifest nem na conferência do que o handler emite.',
+    )
+    this.log.warn(
+      `A action "${action.name}" é do kind "${action.kind}" e declara ${list}, que o runtime só ` +
+        `aplica em actions simple e form. ${effects.join(' ')} Remova ${list} da declaração da ` +
+        'action, no `bindAction` ou no `defineAction`; se a operação precisa de fila ou de ' +
+        'eventos declarados, use uma action simple ou form.',
+      { code: 'runtime.action_field_ignored', action: action.name, kind: action.kind, fields },
+    )
+  }
+
   private registerReactions(reactions: Array<ReactionDef<any>>): void {
     for (const reaction of reactions) {
       if (this.reactions.has(reaction.name)) {
@@ -455,6 +481,12 @@ export class Runtime {
       })
     }
 
+    // Antes de inicializar adapters: é uma checagem do registro, e falhar aqui não deixa
+    // conexão aberta para trás. Sem scheduler, a checagem não roda porque nenhum schedule
+    // executaria: os adapters inicializam e o start falha depois, com
+    // `runtime.eventbus_required` se também faltar event bus, senão `runtime.scheduler_required`.
+    if (this.scheduler !== undefined) this.assertScheduledActionsExist()
+
     for (const adapter of this.allAdapters()) {
       if (adapter.init !== undefined) await adapter.init(this)
       if (adapter.dispose !== undefined) {
@@ -1203,6 +1235,35 @@ export class Runtime {
     }
   }
 
+  /**
+   * Um schedule com nome de action errado dispararia em silêncio para sempre. Schedules com
+   * `enabled: false` ficam de fora: não são registrados e podem apontar para uma action que
+   * ainda não existe neste ambiente.
+   */
+  private assertScheduledActionsExist(): void {
+    const missing = [...this.schedules.values()].filter(
+      (schedule) => schedule.enabled !== false && !this.actions.has(schedule.action),
+    )
+    if (missing.length === 0) return
+    const list = missing
+      .map((schedule) => `"${schedule.name}" → "${schedule.action}"`)
+      .join(', ')
+    throw error({
+      code: 'runtime.schedule_action_not_found',
+      category: 'internal',
+      message:
+        `O runtime não iniciou porque ${
+          missing.length === 1
+            ? 'um schedule aponta para uma action não registrada'
+            : `${missing.length} schedules apontam para actions não registradas`
+        }: ${list}. Corrija o nome em \`action\` ou registre a action no mesmo runtime; para ` +
+        'manter o schedule sem executar, declare `enabled: false`.',
+      meta: {
+        schedules: missing.map((schedule) => ({ schedule: schedule.name, action: schedule.action })),
+      },
+    })
+  }
+
   private registerSchedule(schedule: ScheduleDef): void {
     if (schedule.enabled === false) {
       this.log.info('schedule disabled', { schedule: schedule.name })
@@ -1221,12 +1282,45 @@ export class Runtime {
       typeof schedule.input === 'function'
         ? await (schedule.input as () => unknown | Promise<unknown>)()
         : (schedule.input ?? {})
-    await this.execute(schedule.action, input, {
+    const result = await this.execute(schedule.action, input, {
       user: null,
       tenantId: null,
       can: () => false,
       provenance: { kind: 'schedule', scheduleName: schedule.name },
     })
+    if (result.ok) return
+    // Ninguém espera o resultado de um disparo: sem este registro, a falha só existiria no
+    // audit da action. Action inexistente não chega aqui, porque o start() recusa o schedule.
+    this.log.error(
+      `O schedule "${schedule.name}" não concluiu a action "${schedule.action}" (${result.error.code}). ` +
+        'O agendamento continua ativo e o próximo disparo executa a action de novo. Confira a ' +
+        'mensagem e o audit da action; `auth.unauthenticated` indica que a action agendada precisa ' +
+        'declarar `public: true`.',
+      {
+        schedule: schedule.name,
+        action: schedule.action,
+        code: result.error.code,
+        message: result.error.message,
+        actionId: result.meta.actionId,
+        ...(result.error.cause !== undefined ? { cause: result.error.cause } : {}),
+      },
+    )
+  }
+
+  /**
+   * `ctx.emit` de reaction não publica: encadear reactions por evento ainda não é suportado.
+   * Fora de produção, o descarte vira aviso para que o evento não pareça ter sido entregue.
+   */
+  private buildReactionEmit(reaction: ReactionDef<any>, log: Logger): ReactionContext['emit'] {
+    return async (event) => {
+      if (!this.config.dev) return
+      log.warn(
+        `A reaction "${reaction.name}" chamou ctx.emit('${event}'), mas reactions não publicam ` +
+          'eventos: o evento foi descartado e nenhuma reaction ou integração o recebe. Para ' +
+          'anunciar esse fato, emita-o no handler da action que o produz e declare-o em `emits`.',
+        { code: 'runtime.reaction_emit_ignored', reaction: reaction.name, event },
+      )
+    }
   }
 
   private async runReaction(
@@ -1260,7 +1354,7 @@ export class Runtime {
       tenantId: event.tenant ?? null,
       db: this.data?.contextExtension().db,
       log: reactionLog,
-      emit: noopEmit,
+      emit: this.buildReactionEmit(reaction, reactionLog),
       storage: this.storage ?? null,
       cache: this.cache ?? null,
       // Reação = contexto de sistema; o agente só alcança actions públicas (can nega por
@@ -1411,12 +1505,6 @@ function severityForError(err: any): 'info' | 'warning' | 'error' {
   return 'error'
 }
 
-/**
- * Placeholder pra `ctx.emit` em reactions. Reaction chain (reaction emite
- * eventos novos que disparam outras reactions) entra em v1+.
- */
-const noopEmit: ActionContext['emit'] = async () => undefined
-
 function generateId(): string {
   if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
     return crypto.randomUUID()

package/src/core/types.ts

@@ -255,8 +255,10 @@ export interface User {
 export type CanFn = (permission: string, resource?: unknown) => boolean | Promise<boolean>
 
 /**
- * Função que emite um `DomainEvent`. Disponível em `ActionContext.emit` e
- * `ReactionContext.emit`. Plugada pelo `EventBusAdapter`.
+ * Função que emite um `DomainEvent`. Em `ActionContext.emit`, publica o evento pelo
+ * `EventBusAdapter`. Em `ReactionContext.emit`, descarta o evento sem publicá-lo, porque
+ * reactions ainda não encadeiam outras por evento; com `config.dev` ativo, cada descarte
+ * registra o aviso `runtime.reaction_emit_ignored`.
  */
 export type EmitFn = <T = unknown>(
   event: string,
@@ -293,6 +295,7 @@ export interface ReactionContext {
   tenantId: string | null
   db: unknown
   log: Logger
+  /** Descarta o evento sem publicá-lo: reactions ainda não encadeiam outras. Ver `EmitFn`. */
   emit: EmitFn
   storage: StorageAdapter | null
   cache: CacheAdapter | null

package/src/ui/components/patterns/action-form-card.tsx

@@ -13,6 +13,7 @@ import {
   CardTitle,
 } from "../primitives/card.tsx";
 import { ActionForm, type ActionFormProps } from "./form.tsx";
+import type { HeadingLevel } from "./heading-level.ts";
 import { ButtonGroup } from "../primitives/button-group.tsx";
 
 export interface ActionFormCardProps<
@@ -21,6 +22,12 @@ export interface ActionFormCardProps<
 > extends Omit<ActionFormProps<TInput, TData>, "body" | "footer"> {
   /** Título do header do card. Sem ele, o card começa direto no conteúdo. */
   title?: string;
+  /**
+   * Nível semântico do título (`h1`–`h6`), repassado ao `CardTitle` como `level`. Sem
+   * ele vale o `h3` do Card. Muda só a hierarquia do documento; a escala visual continua
+   * a do Card.
+   */
+  titleLevel?: HeadingLevel;
   /** Subtítulo opcional, abaixo do título. */
   description?: string;
   /** Classes do Card (a superfície). `className` vai pro <form>. */
@@ -29,6 +36,7 @@ export interface ActionFormCardProps<
 
 export function ActionFormCard<TInput extends Record<string, unknown>, TData>({
   title,
+  titleLevel,
   description,
   cardClassName,
   ...rest
@@ -37,7 +45,9 @@ export function ActionFormCard<TInput extends Record<string, unknown>, TData>({
     <Card className={cardClassName}>
       {(title !== undefined || description !== undefined) && (
         <CardHeader>
-          {title !== undefined && <CardTitle>{title}</CardTitle>}
+          {title !== undefined && (
+            <CardTitle level={titleLevel}>{title}</CardTitle>
+          )}
           {description !== undefined && (
             <CardDescription>{description}</CardDescription>
           )}

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

@@ -10,6 +10,8 @@ import {
   type ReactNode,
 } from "react";
 import { cn } from "../../lib/cn.ts";
+import { fillRegionClassName, useFillRegion } from "./fill-region.ts";
+import { headingTags } from "./heading-level.ts";
 import { usePageHeadingPresence } from "./page-heading-context.tsx";
 import {
   SurfaceHeader,
@@ -121,6 +123,7 @@ export function Content({
   ...props
 }: ContentProps): ReactElement {
   const titleId = useId();
+  const fill = useFillRegion();
   const context = {
     element: as,
     frameVariant,
@@ -184,6 +187,7 @@ export function Content({
           data-as="fieldset"
           data-framed={framed}
           data-frame-variant={frameVariant}
+          {...fill.attributes}
           aria-labelledby={ariaLabelledBy}
           className={cn(
             !framed && "space-y-3",
@@ -193,11 +197,12 @@ export function Content({
             framed &&
               frameVariant === "legend" &&
               "space-y-3 rounded-lg border border-border px-4 pb-4",
+            fill.filling && fillRegionClassName,
             className,
           )}
           {...(props as ComponentProps<"fieldset">)}
         >
-          {anatomy}
+          {fill.provide(anatomy)}
         </fieldset>
       ) : (
         <section
@@ -205,15 +210,17 @@ export function Content({
           data-as="section"
           data-framed={framed}
           data-frame-variant={frameVariant}
+          {...fill.attributes}
           aria-labelledby={ariaLabelledBy}
           className={cn(
             "space-y-3",
             framed && "rounded-lg border border-border p-4",
+            fill.filling && fillRegionClassName,
             className,
           )}
           {...(props as ComponentProps<"section">)}
         >
-          {anatomy}
+          {fill.provide(anatomy)}
         </section>
       )}
     </ContentContext.Provider>
@@ -291,15 +298,6 @@ export function ContentHeader({
   );
 }
 
-const headingTags = {
-  1: "h1",
-  2: "h2",
-  3: "h3",
-  4: "h4",
-  5: "h5",
-  6: "h6",
-} as const;
-
 export function ContentTitle({
   className,
   id,
@@ -387,6 +385,7 @@ export function ContentActions({
 
 export function ContentBody({
   className,
+  children,
   ...props
 }: HTMLAttributes<HTMLDivElement>): ReactElement {
   const content = requiredContext(
@@ -394,18 +393,23 @@ export function ContentBody({
     "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.frameVariant === "default" &&
           "clear-left pt-3",
+        fill.filling && fillRegionClassName,
         className,
       )}
       {...props}
-    />
+    >
+      {fill.provide(children)}
+    </div>
   );
 }

package/src/ui/components/patterns/fill-region.ts

@@ -0,0 +1,150 @@
+/**
+ * Propagação da ocupação de altura (interno) — ADR 0024.
+ *
+ * `Page layout="fill"` limita a página à altura do shell; a `Presentation` em página herda
+ * esse limite pela `Page` que ela monta. Para uma região interna ocupar a folga e rolar
+ * sozinha, cada elemento entre a raiz limitada e essa região precisa repassar a altura como
+ * coluna flexível. Este módulo faz essa cadeia se formar sem classes no consumidor:
+ *
+ * - a raiz (`FillRoot`) publica o contexto;
+ * - os elos canônicos (`PageBody`, `Content`, `ContentBody`, o corpo da `Presentation`)
+ *   leem o contexto com `useFillRegion` e o republicam para os filhos;
+ * - a folha (`ActionList`) usa `useFillLeaf`: assume `fill` por padrão quando o elemento
+ *   pai é um elo e se registra na cadeia;
+ * - um elo só vira coluna flexível quando uma folha se registrou abaixo dele. Irmãos sem
+ *   folha mantêm a altura do próprio conteúdo, e uma página `fill` sem lista não muda;
+ * - superfícies com anatomia própria (Card, Dialog, Drawer, Pane) cortam a cadeia com
+ *   `FillBoundary`: a altura delas é decisão delas, inclusive quando um portal as renderiza
+ *   dentro de uma página `fill`.
+ *
+ * O registro acontece em `useLayoutEffect`, então as classes chegam antes da primeira pintura.
+ */
+
+import {
+  createContext,
+  createElement,
+  useContext,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+  type RefObject,
+} from "react";
+
+export type FillLayout = "flow" | "fill";
+
+interface FillChain {
+  /** Anuncia uma folha abaixo deste elo; devolve a retirada do anúncio. */
+  register(): () => void;
+}
+
+const FillChainContext = createContext<FillChain | null>(null);
+
+/** A raiz já tem altura limitada: não há o que propagar acima dela. */
+const rootChain: FillChain = { register: () => () => {} };
+
+/** Classes de um elo que repassa a altura à folha registrada abaixo dele. */
+export const fillRegionClassName = "flex min-h-0 flex-1 flex-col";
+
+/**
+ * Atributo que marca um elo da cadeia no DOM: `"true"` quando repassa a altura, `"false"`
+ * quando está na cadeia sem folha abaixo. A folha só assume `fill` implícito quando o
+ * elemento pai o carrega — um contêiner próprio no meio não repassa a altura.
+ */
+export const fillRegionAttribute = "data-fill";
+
+/** Publica a cadeia quando `active`; caso contrário a interrompe. */
+export function FillRoot({
+  active,
+  children,
+}: {
+  active: boolean;
+  children?: ReactNode;
+}): ReactElement {
+  return createElement(
+    FillChainContext.Provider,
+    { value: active ? rootChain : null },
+    children,
+  );
+}
+
+/** Interrompe a cadeia: o conteúdo abaixo decide a própria altura. */
+export function FillBoundary({
+  children,
+}: {
+  children?: ReactNode;
+}): ReactElement {
+  return createElement(FillChainContext.Provider, { value: null }, children);
+}
+
+export interface FillRegion {
+  /** O elo está em uma cadeia `fill`, com ou sem folha abaixo. */
+  inChain: boolean;
+  /** Uma folha se registrou abaixo: o elo deve repassar a altura. */
+  filling: boolean;
+  /** Atributos do elemento do elo. */
+  attributes: { "data-fill"?: "true" | "false" };
+  /** Republica a cadeia para os filhos do elo. */
+  provide(children: ReactNode): ReactElement;
+}
+
+/** Elo da cadeia: lê o contexto, conta as folhas abaixo e o republica. */
+export function useFillRegion(): FillRegion {
+  const parent = useContext(FillChainContext);
+  const [leaves, setLeaves] = useState(0);
+  const chain = useMemo<FillChain | null>(
+    () =>
+      parent === null
+        ? null
+        : {
+            register() {
+              setLeaves((count) => count + 1);
+              const releaseParent = parent.register();
+              let registered = true;
+              return () => {
+                if (!registered) return;
+                registered = false;
+                setLeaves((count) => Math.max(0, count - 1));
+                releaseParent();
+              };
+            },
+          },
+    [parent],
+  );
+  const inChain = parent !== null;
+  const filling = inChain && leaves > 0;
+  return {
+    inChain,
+    filling,
+    attributes: inChain ? { "data-fill": filling ? "true" : "false" } : {},
+    provide: (children) =>
+      createElement(FillChainContext.Provider, { value: chain }, children),
+  };
+}
+
+/**
+ * Folha da cadeia. Sem `layout` explícito, assume `fill` quando o elemento pai é um elo;
+ * com `layout="fill"` explícito, registra-se mesmo sob um contêiner próprio, que passa a
+ * ser responsabilidade de quem o escreveu. `layout="flow"` nunca se registra.
+ */
+export function useFillLeaf<TElement extends HTMLElement>(
+  layout: FillLayout | undefined,
+): { layout: FillLayout; ref: RefObject<TElement | null> } {
+  const chain = useContext(FillChainContext);
+  const ref = useRef<TElement | null>(null);
+  const [linked, setLinked] = useState(false);
+  useLayoutEffect(() => {
+    setLinked(
+      chain !== null &&
+        ref.current?.parentElement?.hasAttribute(fillRegionAttribute) === true,
+    );
+  }, [chain]);
+  const resolved = layout ?? (linked ? "fill" : "flow");
+  useLayoutEffect(() => {
+    if (chain === null || resolved !== "fill") return undefined;
+    return chain.register();
+  }, [chain, resolved]);
+  return { layout: resolved, ref };
+}

package/src/ui/components/patterns/heading-level.ts

@@ -0,0 +1,16 @@
+/**
+ * Nível de heading (interno): hierarquia do documento, separada do tamanho visual.
+ *
+ * A ADR 0023 fixa a regra: `h1`–`h6` expressam hierarquia; a escala do título vem da
+ * família e do layout. As duas decisões nunca se misturam num mesmo valor.
+ */
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export const headingTags = {
+  1: "h1",
+  2: "h2",
+  3: "h3",
+  4: "h4",
+  5: "h5",
+  6: "h6",
+} as const satisfies Record<HeadingLevel, `h${HeadingLevel}`>;