@softize/opus 15.2.2 → 16.1.0

package/src/core/presentation.ts

@@ -0,0 +1,512 @@
+import { z } from "zod";
+import type { ActionContract } from "./contracts.ts";
+
+const identifierSchema = z.string().regex(/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/);
+
+export type PresentationJsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | PresentationJsonValue[]
+  | { [key: string]: PresentationJsonValue };
+
+export const presentationJsonValueSchema: z.ZodType<PresentationJsonValue> =
+  z.lazy(() =>
+    z.union([
+      z.string(),
+      z.number().finite(),
+      z.boolean(),
+      z.null(),
+      z.array(presentationJsonValueSchema),
+      z.record(presentationJsonValueSchema),
+    ]),
+  );
+
+const presentationInputSchema = z.record(presentationJsonValueSchema);
+
+export const presentationSurfaceSchema = z.enum(["page", "dialog", "drawer"]);
+export type PresentationSurface = z.infer<typeof presentationSurfaceSchema>;
+
+export const presentationBindingSchema = z.discriminatedUnion("source", [
+  z.object({ source: z.literal("route"), param: identifierSchema }).strict(),
+  z.object({ source: z.literal("record"), field: z.string().min(1) }).strict(),
+  z.object({ source: z.literal("item"), field: z.string().min(1) }).strict(),
+  z.object({ source: z.literal("selection") }).strict(),
+  z.object({ source: z.literal("session"), field: z.string().min(1) }).strict(),
+  z.object({ source: z.literal("result"), field: z.string().min(1) }).strict(),
+  z
+    .object({ source: z.literal("fixed"), value: presentationJsonValueSchema })
+    .strict(),
+  z.object({ source: z.literal("now") }).strict(),
+]);
+export type PresentationBinding = z.infer<typeof presentationBindingSchema>;
+
+export const presentationEffectSchema = z.discriminatedUnion("effect", [
+  z
+    .object({
+      effect: z.literal("refresh"),
+      action: z.string().min(1).optional(),
+    })
+    .strict(),
+  z.object({ effect: z.literal("close") }).strict(),
+  z.object({ effect: z.literal("back") }).strict(),
+  z
+    .object({
+      effect: z.literal("navigate"),
+      presentation: identifierSchema,
+      surface: presentationSurfaceSchema.optional(),
+      input: z.record(presentationBindingSchema).default({}),
+      mode: z.enum(["push", "replace"]).default("push"),
+    })
+    .strict(),
+]);
+export type PresentationEffect = z.infer<typeof presentationEffectSchema>;
+export type PresentationEffectInput = z.input<typeof presentationEffectSchema>;
+
+const presentationTargetSchema = z
+  .object({
+    presentation: identifierSchema,
+    surface: presentationSurfaceSchema.optional(),
+  })
+  .strict();
+
+const presentationCommandSchema = z
+  .object({
+    action: z.string().min(1),
+    placement: z.enum(["header", "footer"]),
+    input: z.record(presentationBindingSchema).default({}),
+    target: presentationTargetSchema.optional(),
+    blocking: z.enum(["action", "group", "surface"]).default("action"),
+    onSuccess: z.array(presentationEffectSchema).default([]),
+  })
+  .strict();
+
+const presentationFieldSchema = z
+  .object({
+    key: z.string().min(1),
+    label: z.string().min(1),
+    empty: z.string().min(1).optional(),
+  })
+  .strict();
+
+const presentationBodySchema = z
+  .object({
+    action: z.string().min(1),
+    input: z.record(presentationBindingSchema).default({}),
+    fields: z.array(presentationFieldSchema).min(1).optional(),
+    open: z
+      .object({
+        presentation: identifierSchema,
+        surface: presentationSurfaceSchema.optional(),
+        input: z.record(presentationBindingSchema).default({}),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+
+export const presentationSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    id: identifierSchema,
+    title: z.string().min(1),
+    body: presentationBodySchema,
+    actions: z.array(presentationCommandSchema).default([]),
+  })
+  .strict();
+
+export type PresentationDefinition = z.infer<typeof presentationSchema>;
+export type PresentationDefinitionInput = z.input<typeof presentationSchema>;
+export type PresentationCommand = PresentationDefinition["actions"][number];
+type DefaultedProperty<Input, Key extends PropertyKey, Output> =
+  Key extends keyof Input
+    ? undefined extends Input[Key]
+      ? Exclude<Input[Key], undefined> | Output
+      : Input[Key] & Output
+    : Output;
+type NavigateEffect = Extract<PresentationEffect, { effect: "navigate" }>;
+type DefinedPresentationEffect<Effect> = Effect extends { effect: "navigate" }
+  ? Omit<Effect, "input" | "mode"> &
+      Omit<NavigateEffect, "input" | "mode"> & {
+        input: DefaultedProperty<Effect, "input", NavigateEffect["input"]>;
+        mode: DefaultedProperty<Effect, "mode", NavigateEffect["mode"]>;
+      }
+  : Effect & PresentationEffect;
+type DefinedPresentationEffects<Input, Key extends PropertyKey> =
+  Key extends keyof Input
+    ? undefined extends Input[Key]
+      ? PresentationCommand["onSuccess"]
+      : Input[Key] extends readonly unknown[]
+        ? {
+            -readonly [Index in keyof Input[Key]]: DefinedPresentationEffect<
+              Input[Key][Index]
+            >;
+          }
+        : PresentationCommand["onSuccess"]
+    : PresentationCommand["onSuccess"];
+type PresentationOpen = NonNullable<PresentationDefinition["body"]["open"]>;
+type DefinedPresentationOpen<Open> = Open extends object
+  ? Omit<Open, "input"> &
+      Omit<PresentationOpen, "input"> & {
+        input: DefaultedProperty<Open, "input", PresentationOpen["input"]>;
+      }
+  : never;
+type DefinedPresentationBody<Body extends PresentationDefinitionInput["body"]> =
+  Omit<Body, "input" | "open"> &
+    Omit<PresentationDefinition["body"], "input" | "open"> & {
+      input: DefaultedProperty<
+        Body,
+        "input",
+        PresentationDefinition["body"]["input"]
+      >;
+    } & ("open" extends keyof Body
+      ? undefined extends Body["open"]
+        ? { open?: DefinedPresentationOpen<Exclude<Body["open"], undefined>> }
+        : { open: DefinedPresentationOpen<Body["open"]> }
+      : { open?: PresentationDefinition["body"]["open"] });
+type DefinedPresentationCommand<Command> = Command extends object
+  ? Omit<Command, "input" | "blocking" | "onSuccess"> &
+      Omit<PresentationCommand, "input" | "blocking" | "onSuccess"> & {
+        input: DefaultedProperty<Command, "input", PresentationCommand["input"]>;
+        blocking: DefaultedProperty<
+          Command,
+          "blocking",
+          PresentationCommand["blocking"]
+        >;
+        onSuccess: DefinedPresentationEffects<Command, "onSuccess">;
+      }
+  : never;
+type DefinedPresentationActions<T extends PresentationDefinitionInput> =
+  T extends { actions: infer Actions extends readonly unknown[] }
+    ? {
+        -readonly [Index in keyof Actions]: DefinedPresentationCommand<
+          Actions[Index]
+        >;
+      }
+    : PresentationDefinition["actions"];
+export type DefinedPresentation<T extends PresentationDefinitionInput> = Omit<
+  T,
+  "body" | "actions"
+> &
+  Omit<PresentationDefinition, "body" | "actions"> & {
+    body: DefinedPresentationBody<T["body"]>;
+    actions: DefinedPresentationActions<T>;
+  };
+
+export const presentationFrameSchema = z
+  .object({
+    presentationId: identifierSchema,
+    surface: presentationSurfaceSchema,
+    input: presentationInputSchema.default({}),
+  })
+  .strict();
+
+export const presentationInvocationSchema = presentationFrameSchema
+  .extend({
+    schemaVersion: z.literal(1),
+    stack: z.array(presentationFrameSchema).default([]),
+  })
+  .strict();
+
+export type PresentationFrame = z.infer<typeof presentationFrameSchema>;
+export type PresentationInvocation = z.infer<
+  typeof presentationInvocationSchema
+>;
+
+export interface PresentationTransition {
+  invocation: PresentationInvocation | null;
+  refresh: Array<string | null>;
+  exit?: "back" | "close";
+}
+
+export interface PresentationDiagnostic {
+  level: "info" | "warning" | "error";
+  code: string;
+  message: string;
+  path?: string;
+}
+
+export interface PresentationInspectionSnapshot {
+  definition: unknown;
+  invocation?: unknown;
+  resolved?: unknown;
+  diagnostics: PresentationDiagnostic[];
+}
+
+export interface PresentationActionRegistry {
+  readonly [name: string]: ActionContract;
+}
+
+export interface PresentationBindingContext {
+  route?: Readonly<Record<string, unknown>>;
+  record?: Readonly<Record<string, unknown>>;
+  item?: Readonly<Record<string, unknown>>;
+  selection?: readonly unknown[];
+  session?: Readonly<Record<string, unknown>>;
+  result?: Readonly<Record<string, unknown>>;
+  now?: () => Date;
+}
+
+export function definePresentation<const T extends PresentationDefinitionInput>(
+  definition: T,
+): DefinedPresentation<T> {
+  return presentationSchema.parse(definition) as unknown as DefinedPresentation<T>;
+}
+
+export function definePresentationInvocation(
+  invocation: z.input<typeof presentationInvocationSchema>,
+): PresentationInvocation {
+  return presentationInvocationSchema.parse(invocation);
+}
+
+function frameFromInvocation(
+  invocation: PresentationInvocation,
+): PresentationFrame {
+  return {
+    presentationId: invocation.presentationId,
+    surface: invocation.surface,
+    input: invocation.input,
+  };
+}
+
+export function openPresentation(
+  invocation: PresentationInvocation,
+  target: PresentationFrame,
+  mode: "push" | "replace" = "push",
+): PresentationInvocation {
+  const parsedTarget = presentationFrameSchema.parse(target);
+  return definePresentationInvocation({
+    schemaVersion: 1,
+    ...parsedTarget,
+    stack:
+      mode === "push"
+        ? [...invocation.stack, frameFromInvocation(invocation)]
+        : invocation.stack,
+  });
+}
+
+export function backPresentation(
+  invocation: PresentationInvocation,
+): PresentationInvocation | null {
+  const parent = invocation.stack.at(-1);
+  if (parent === undefined) return null;
+  return definePresentationInvocation({
+    schemaVersion: 1,
+    ...parent,
+    stack: invocation.stack.slice(0, -1),
+  });
+}
+
+export function closePresentation(invocation: PresentationInvocation): null {
+  if (invocation.surface === "page") {
+    throw new Error(
+      "Uma Presentation em page não pode receber o efeito close.",
+    );
+  }
+  return null;
+}
+
+export function applyPresentationEffects(
+  invocation: PresentationInvocation,
+  effects: readonly PresentationEffectInput[],
+  context: PresentationBindingContext = {},
+): PresentationTransition {
+  let current: PresentationInvocation | null = invocation;
+  const refresh: Array<string | null> = [];
+  let exit: PresentationTransition["exit"];
+
+  for (const rawEffect of effects) {
+    const effect = presentationEffectSchema.parse(rawEffect);
+    if (effect.effect === "refresh") {
+      refresh.push(effect.action ?? null);
+      continue;
+    }
+    if (current === null) {
+      throw new Error(
+        `O efeito ${effect.effect} não possui Presentation ativa.`,
+      );
+    }
+    if (effect.effect === "close") {
+      current = closePresentation(current);
+      exit = "close";
+      continue;
+    }
+    if (effect.effect === "back") {
+      current = backPresentation(current);
+      if (current === null) exit = "back";
+      continue;
+    }
+    current = openPresentation(
+      current,
+      {
+        presentationId: effect.presentation,
+        surface: effect.surface ?? current.surface,
+        input: resolvePresentationBindings(effect.input, context) as Record<
+          string,
+          PresentationJsonValue
+        >,
+      },
+      effect.mode,
+    );
+  }
+
+  return {
+    invocation: current,
+    refresh,
+    ...(exit === undefined ? {} : { exit }),
+  };
+}
+
+const sensitiveKeyPattern =
+  /(?:authorization|cookie|password|secret|token|api[-_]?key)/iu;
+
+export function redactPresentationInspectionValue(
+  value: unknown,
+  key = "",
+): unknown {
+  if (sensitiveKeyPattern.test(key)) return "[REDACTED]";
+  if (Array.isArray(value)) {
+    return value.map((item) => redactPresentationInspectionValue(item));
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([entryKey, entryValue]) => [
+        entryKey,
+        redactPresentationInspectionValue(entryValue, entryKey),
+      ]),
+    );
+  }
+  return value;
+}
+
+export function createPresentationInspectionSnapshot(input: {
+  definition: unknown;
+  invocation?: unknown;
+  resolved?: unknown;
+  diagnostics?: readonly PresentationDiagnostic[];
+}): PresentationInspectionSnapshot {
+  return redactPresentationInspectionValue({
+    definition: input.definition,
+    ...(input.invocation === undefined ? {} : { invocation: input.invocation }),
+    ...(input.resolved === undefined ? {} : { resolved: input.resolved }),
+    diagnostics: input.diagnostics ?? [],
+  }) as PresentationInspectionSnapshot;
+}
+
+export function validatePresentations(
+  input: unknown,
+  actions: PresentationActionRegistry,
+): PresentationDefinition[] {
+  const parsed = z.array(presentationSchema).parse(input);
+  const byId = new Map<string, PresentationDefinition>();
+  const problems: string[] = [];
+
+  for (const presentation of parsed) {
+    if (byId.has(presentation.id))
+      problems.push(`Presentation “${presentation.id}” duplicada.`);
+    byId.set(presentation.id, presentation);
+
+    const bodyAction = actions[presentation.body.action];
+    if (bodyAction === undefined) {
+      problems.push(
+        `A action “${presentation.body.action}” não está disponível.`,
+      );
+    } else if (bodyAction.kind === "simple") {
+      problems.push(
+        `A action simple “${bodyAction.name}” não pode ocupar o body.`,
+      );
+    } else {
+      if (
+        bodyAction.kind === "view" &&
+        presentation.body.fields === undefined
+      ) {
+        problems.push(
+          `A Presentation “${presentation.id}” precisa declarar fields para a view.`,
+        );
+      }
+      if (
+        bodyAction.kind !== "view" &&
+        presentation.body.fields !== undefined
+      ) {
+        problems.push(`Fields só podem ser declarados para uma action view.`);
+      }
+      if (bodyAction.kind !== "list" && presentation.body.open !== undefined) {
+        problems.push(`Open só pode ser declarado para uma action list.`);
+      }
+    }
+
+    for (const command of presentation.actions) {
+      const action = actions[command.action];
+      if (action === undefined) {
+        problems.push(`A action “${command.action}” não está disponível.`);
+      } else if (action.kind === "simple" && command.target !== undefined) {
+        problems.push(
+          `A action simple “${command.action}” executa diretamente e não aceita target.`,
+        );
+      } else if (action.kind !== "simple" && command.target === undefined) {
+        problems.push(
+          `A action ${action.kind} “${command.action}” precisa abrir outra Presentation.`,
+        );
+      }
+    }
+  }
+
+  for (const presentation of parsed) {
+    const open = presentation.body.open;
+    if (open !== undefined && !byId.has(open.presentation)) {
+      problems.push(
+        `A lista “${presentation.id}” abre a Presentation inexistente “${open.presentation}”.`,
+      );
+    }
+    for (const command of presentation.actions) {
+      for (const effect of command.onSuccess) {
+        if (effect.effect === "navigate" && !byId.has(effect.presentation)) {
+          problems.push(
+            `A action “${command.action}” navega para a Presentation inexistente “${effect.presentation}”.`,
+          );
+        }
+      }
+      if (command.target === undefined) continue;
+      const target = byId.get(command.target.presentation);
+      if (target === undefined) {
+        problems.push(
+          `A action “${command.action}” abre a Presentation inexistente “${command.target.presentation}”.`,
+        );
+      } else if (target.body.action !== command.action) {
+        problems.push(
+          `A Presentation “${target.id}” usa “${target.body.action}”, mas foi aberta por “${command.action}”.`,
+        );
+      }
+    }
+  }
+
+  if (problems.length > 0) throw new Error(problems.join("\n"));
+  return parsed;
+}
+
+export function resolvePresentationBinding(
+  binding: PresentationBinding,
+  context: PresentationBindingContext,
+): unknown {
+  if (binding.source === "route") return context.route?.[binding.param];
+  if (binding.source === "record") return context.record?.[binding.field];
+  if (binding.source === "item") return context.item?.[binding.field];
+  if (binding.source === "selection") return context.selection;
+  if (binding.source === "session") return context.session?.[binding.field];
+  if (binding.source === "result") return context.result?.[binding.field];
+  if (binding.source === "fixed") return binding.value;
+  return (context.now ?? (() => new Date()))().toISOString();
+}
+
+export function resolvePresentationBindings(
+  bindings: Readonly<Record<string, PresentationBinding>>,
+  context: PresentationBindingContext,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(bindings).map(([key, binding]) => [
+      key,
+      resolvePresentationBinding(binding, context),
+    ]),
+  );
+}

package/src/presentation/index.ts

@@ -0,0 +1 @@
+export * from "../core/presentation.ts";

package/src/ui/components/patterns/action-list-dialog.tsx

@@ -11,20 +11,22 @@
  * - `empty` sobrepõe o vazio derivado (ex.: form inline de criar aberto ⇒ children).
  */
 
-import type { ReactNode } from 'react'
+import { useId, type ReactNode } from 'react'
 import { cn } from '../../lib/cn.ts'
 import {
   Dialog,
   DialogBody,
   DialogContent,
-  DialogDescription,
   DialogHeader,
   DialogTitle,
 } from '../primitives/dialog.tsx'
 import { ActionList } from './list.tsx'
 import type { ListAction } from '../../../core/index.ts'
 
-export interface ActionListDialogProps<TItem, TInput extends Record<string, unknown> = Record<string, unknown>> {
+export interface ActionListDialogProps<
+  TItem,
+  TInput extends Record<string, unknown> = Record<string, unknown>,
+> {
   /** A ListAction do Opus (estrutural: name + kind — o mesmo contrato da família). */
   action: { name: string; kind: 'list' }
   /** Input da action (o escopo base; ex.: { workspaceId }). Mudou, re-busca. */
@@ -32,7 +34,8 @@ export interface ActionListDialogProps<TItem, TInput extends Record<string, unkn
   open: boolean
   onOpenChange: (open: boolean) => void
   title: string
-  description?: string
+  /** Conteúdo relevante apresentado antes da lista, como texto ou Alert. */
+  intro?: ReactNode
   /** Nota à esquerda da linha de ações (contexto curto). O total já mora no rodapé. */
   note?: ReactNode
   /** Ação à direita da linha — em geral o botão de criar. */
@@ -51,13 +54,16 @@ export interface ActionListDialogProps<TItem, TInput extends Record<string, unkn
   children: (items: TItem[], refetch: () => Promise<void>) => ReactNode
 }
 
-export function ActionListDialog<TItem, TInput extends Record<string, unknown> = Record<string, unknown>>({
+export function ActionListDialog<
+  TItem,
+  TInput extends Record<string, unknown> = Record<string, unknown>,
+>({
   action,
   input,
   open,
   onOpenChange,
   title,
-  description,
+  intro,
   note,
   actions,
   emptyMessage,
@@ -68,16 +74,27 @@ export function ActionListDialog<TItem, TInput extends Record<string, unknown> =
   className,
   children,
 }: ActionListDialogProps<TItem, TInput>): React.ReactElement {
+  const introId = useId()
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
-      <DialogContent className={cn('sm:max-w-3xl', className)}>
+      <DialogContent
+        className={cn('sm:max-w-3xl', className)}
+        aria-describedby={intro === undefined ? undefined : introId}
+      >
         <DialogHeader>
           <DialogTitle>{title}</DialogTitle>
-          {description !== undefined && <DialogDescription>{description}</DialogDescription>}
         </DialogHeader>
         <DialogBody>
+          {intro !== undefined && (
+            <div id={introId} className="mb-4">
+              {intro}
+            </div>
+          )}
           {(note !== undefined || actions !== undefined) && (
-            <div data-slot="action-list-dialog-toolbar" className="mb-2 flex min-h-8 items-center justify-between gap-4">
+            <div
+              data-slot="action-list-dialog-toolbar"
+              className="mb-2 flex min-h-8 items-center justify-between gap-4"
+            >
               <div className="min-w-0 text-xs text-muted-foreground/70">{note}</div>
               {actions}
             </div>